Importing Components

A catalogue can take a component from another catalogue package: a subsystem shared by several platforms (a power unit, a battery, an on-board computer), published once and validated once. YAML anchors are not enough for this: they do not cross files, and they would copy the definition instead of referring to a versioned package.

package: platform-v4
version: 1.0.0
uses:
  common-eps: 2.x
components:
  pcdu: {from: common-eps}          # component pcdu of common-eps, same name
  eps:  {from: common-eps.battery}  # component battery of common-eps, renamed eps
  tcu:                              # a component of the platform itself
    instances: tcu_id
    measures:
      mode: {type: tcu_operating_mode}

Declaring dependencies: uses#

uses maps each imported package to a version requirement:

The compiler resolves each requirement against the catalogue packages of the configuration repository (packages/<name>/catalogue.yaml), and those it takes from other repositories (stellar.yaml, see Several repositories), and takes the highest version that satisfies it. An unknown package or version is an error (catalogue::unresolved-import), and so is a cycle of imports between packages (catalogue::import-cycle). A package in uses from which no component is imported gives a warning (catalogue::unused-import).

An imported package may itself import components from others.

Importing a component: from#

The package must be listed in uses (catalogue::undeclared-import), and must have the component (catalogue::unknown-component).

Rules#

• Taken as is. An imported component declares nothing but from (and a description): no instances, measure, telecommand, derived measure, alarm, file types or transfer of its own (catalogue::import-extended). The validation of its package stays valid. To extend it, publish a new version of the original package.
• Enums follow the component. The enums the component uses (its instances, the types of its measures, derived measures and arguments) are added to the catalogue under their own name. An enum of the same name already in the catalogue is an error, even with identical values (catalogue::duplicate-enum): rename one of them. Two components imported from the same package version share their enums without conflict.
• Version frozen by the compilation. The version resolved for each import is recorded in the compiled catalogue. A new version of the imported package changes the platform only when it is compiled again; since a released catalogue never changes in place, publish a new version of the platform to take it.

Imports, drivers and procedures#

A platform that imports components of a package serves that package for them: what was written and validated for the subsystem alone — its driver, its procedures, their lock — works on the platform unchanged. The camera of a payload supplier, integrated on a satellite:

package: cubesat-6u
version: 1.0.0
uses:
  hsc-100: 1.x
components:
  camera: {from: hsc-100}            # same name
  imager: {from: hsc-100.camera}     # or renamed: the camera of hsc-100 is the imager here

Drivers#

On the platform, an imported component is a component like any other: a driver of cubesat-6u covers imager.* with the rest. A link may also take the driver of the package for the components imported from it:

sat-1:
  platform: cubesat-6u@1.0.0
  links:
    nominal: {driver: cubesat-6u-ccsds@1, gateway: bench-rf-1, default: true}
    camera:  {driver: hsc-100-csp@1, gateway: bench-can-1, components: [imager]}

• The driver's catalogue requirement (hsc-100@^1.0) accepts the version of the package that the platform imports, hsc-100@1.0.0 here.
• The link carries only components imported from that package: list them in components (a link without components carries the whole platform, which then must import everything from the package).
• The driver covers those components under their names in the package (camera.*), not the components of the package the platform leaves out.
• A renamed component keeps its name in the package for its driver: the reconciler gives the binding the names to translate (components: imager → camera), and the SDKs translate both ways. The driver receives camera.power_on; its camera.state samples are stored as imager.state of sat-1.

The refusals say why, such as driver `hsc-100-csp-1` implements `hsc-100@^2.0`, but `cubesat-6u@1.0.0` imports `hsc-100@1.0.0` or … the link carries `obc`, which `cubesat-6u@1.0.0` does not import from `hsc-100` . See Links.

Procedures#

A procedure written for the package (uses cam: hsc-100) runs on a target whose platform imports the components it uses:

• it keeps the names of the package: cam.camera.state is imager.state of sat-1; the executor translates telecommands, measures, parameters, files and links;
• the version the platform imports is the one the library was compiled against (run::catalogue-version): the lock of the library, which records the hash of hsc-100, stays valid;
• a procedure that uses a component the platform does not import is refused when the run is resolved (run::not-imported), such as « Release cover » on a platform that imports only the camera;
• a target of another platform that imports nothing of the package is refused (run::wrong-platform).

Procedures of the platform address the components under their names on the platform: sat.imager.state.

Alarms#

The alarms of an imported component are raised on the target under its name on the platform (imager), from the samples translated by the SDK. A reaction (on_raise) runs a procedure of a library of the platform when one defines it; otherwise one of a library of the package the component comes from, on the target through the import.