Caribou Satellite#

Name	Caribou
Subtitle	Constellation Satellite for controlling Caribou devices via their Peary interface
Category	Readout Systems
Language	C++
Website	constellation/satellites/caribou

Description#

Operate devices integrated into the Peary software and the Caribou ecosystem. This satellite provides a unified interface to the Peary device classes and can operate multiple devices in parallel for applications such as beam telescopes. Registers and settings can be specified individually for every device and are passed on to the respective Peary configurations.

It is possible to decide for every device individually whether it will be powered on, is configured or partakes in data acquisition. This allows for example operation active sensors which are powered through the Caribou Carboard power supplies but which does not provide any data, simultaneously with a readout chip which requires power, configuration, and provides a data stream. The configuration takes place through the do_power, do_configure and do_acquire parameters of each of the device sections.

Note

It should be noted that data can only be read out from devices of a single type in order to avoid ambiguities in data storage and decoding. This means, while multiple devices can have do_acquire = true, they all have to share the same type parameter. Every data record sent to the Constellation is marked with a header tag name containing the corresponding device name.

The satellite provides a flexible scheme for configuring telemetry data. Adding a new entry to the metrics section allows to configure a new metric for any of the configured devices. This means, e.g. voltages or currents emitted during the run as well as registers of the device or firmware memory registers can be freely configured and adapted to the respective device configuration. As an example, the following metrics entry would register a metric broadcasted under the name CP2_VDDD, and which reads a voltage named vddd from the device CP2 which was configured earlier”

[Caribou.MySetup.metrics.CP2_VDDD]
type = "voltage"
device = "CP2"
identifier = "vddd"

This satellite supports the reconfiguration transition. Any registers or memory registers known to the configured Caribou devices can be updated during reconfiguration.

FSM State Implementations#

The satellite interfaces the Peary device manager to add devices and to control them. The following actions are performed in the different FSM stages:

Initialization: All devices to be instantiated is taken from the configuration section devices. Device types specified via their type parameter are case sensitive and their libraries have to be available in the linked Peary installation. For each device, registers and memory registers can be specified via the registers and memories sections of the device configuration, respectively. All other keys present in the device configuration section will be converted to strings and passed to the Peary configuration verbatim.

In addition, the following configuration keys are available for the initialization:
- peary_verbosity: Set the Peary-internal logging verbosity for output on the terminal of the satellite. Please refer to the Peary documentation for more information. The verbosity can be changed at any point using the peary_verbosity command this satellite exposes.
- number_of_frames: This key allows buffering of multiple Caribou device frames into a single Constellation data message. If set to a value larger than 1, frames are first buffered and upon reaching the desired buffer depth, they are collectively sent. A value of, for example, number_of_frames = 100 would therefore result in one message being sent every 100 frames read from the device. This message would contain 100 frames with the individual data blocks. This can be used to reduce the number of packets sent via the network and to better make use of available bandwidth.
Launching: During launch, the devices configured for being powered up via do_power are powered using Peary’s powerOn() command. After this, the satellite waits for one second in order to allow the power to stabilize. Then, the configure() command of the Peary device interface is called for every device marked for configuration via do_configure.
Reconfiguration: Any register returned by the device by list_registers() or memory registers from list_memories() can be updated during reconfiguration. The satellite attempts to read any of these values from the provided reconfiguration object and, if successful, updates the devices.
Start / Stop: During start and stop, the corresponding Peary device functions daqStart() and daqStop() are called for every device marked for data taking via do_acquire.

Since the Peary device libraries are not thread-safe, all access to Peary libraries is guarded using a std::lock_guard with a central mutex to avoid concurrent device access. The Peary device manager itself ensures that no two instances are executed on the same hardware. This means, only one Constellation satellite can be started per Caribou board.

Parameters#

The following parameters are read and interpreted by this satellite:

Parameter	Description	Type	Default Value
`peary_verbosity`	Verbosity of the Peary logger. See custom commands for possible values. The verbosity can be changed at any time using the custom command described below	String	`INFO`
`devices`	Section for Caribou devices to be operated	Section	–
`metrics`	Section to define metrics this satellite should provide	Section	–

Devices Section#

The section devices holds individual sections for all devices that should be instantiated, configured and read out. The section name will be used as the device name and can be freely chosen, the parameters interpreted for each device are listed in the following:

Parameter	Description	Type	Default Value
`type`	Type of the Caribou device to be instantiated, corresponds to the (case-sensitive) device class name	String	–
`do_power`	Boolean so select whether this device should be powered via Peary’s `powerOn()` and `powerOff()` methods	Boolean	`true`
`do_configure`	Boolean so select whether this device should be configured via Peary’s `configure()` method or not	Boolean	`true`
`do_acquire`	Boolean so select whether a DAQ session should be started for this device, and whether readout should be attempted via the `getRawData()` method	Boolean	`true`
`registers`	Section for device registers. Each entry will be passed on to the Peary configuration object for the corresponding device	Section	–
`memories`	Section for device memory registers. Each entry will be passed on to the Peary configuration object for the corresponding device	Section	–

Metrics Section#

The section metrics holds individual sections for all metrics that should be provided by this satellite. The section name will be converted to upper-case and used as the metric name, the parameters interpreted for each metric are listed in the following:

Parameter	Description	Type	Default Value
`type`	Type of metric, possible values are `register`, `memory`, `voltage` and `current`	String	–
`device`	Name of the device this metric should be queried from. This device needs to be known from the `devices` section	String	–
`identifier`	Identifier of the metric. This is the register or memory name, or the name of the voltage/current assigned by the device	String	–
`units`	Units this metric is provided in, distributed along with the metric value. If not set, this defaults to `"A"` for type `current` and `"V"` for type `voltage`	String	`""`
`description`	Description distributed along with the metric value	String	`""`
`interval`	Interval in seconds for sending this metric	Integer	10s

Configuration Example#

An example configuration for this satellite which could be dropped into a Constellation configuration as a starting point

[Caribou.MySetup]
peary_verbosity = "INFO"

[Caribou.MySetup.devices.CP2]
type = "CLICpix2"
registers.latency = 12

[Caribou.MySetup.devices.Sensor]
type = "C3PD"
acquire = false

[Caribou.MySetup.metrics.CP2_VDDD]
type = "voltage"
device = "CP2"
identifier = "vddd"

The equivalent in YAML format is

Caribou:
  MySetup:
    peary_verbosity: "INFO"
    devices:
      CP2:
        type: "CLICpix2"
        registers:
          latency: 12
      Sensor:
        type: "C3PD"
        acquire: false
    metrics:
      CP2_VDDD:
        type: "voltage"
        device: "CP2"
        identifier: "vddd"

Custom Commands#

The Caribou satellite exposes the following commands via the control interface. None of these commands alter the state of the attached device, but they only provide additional information on the device and its periphery.

Command	Description	Arguments	Return Value	Allowed States
`peary_verbosity`	Set verbosity of the Peary logger	Device name, desired verbosity, as `string` values. Possible verbosity values are `FATAL`, `STATUS`, `ERROR`, `WARNING`, `INFO`, `DEBUG` and `TRACE`	-	all
`get_peary_verbosity`	Get the currently configured verbosity of the Peary logger	Device name as `string`	Current Peary verbosity level	all
`list_registers`	List all available register names for the attached Caribou device	Device name as `string`	List of registers, array of `string`	`INIT`, `ORBIT`, `RUN`
`list_memories`	List all memory registers for the attached Caribou device	Device name as `string`	List of memory registers, array of `string`	`INIT`, `ORBIT`, `RUN`
`get_voltage`	Get selected output voltage of the attached Caribou device	Device name and voltage name as `string` values	Voltage reading in V, `double`	`INIT`, `ORBIT`, `RUN`
`get_current`	Get selected output current of the attached Caribou device	Device name and current name as `string` values	Current reading in A, `double`	`INIT`, `ORBIT`, `RUN`
`get_power`	Get selected output power of the attached Caribou device	Device name and power monitor name, as `string` values	Power reading in W, `double`	`INIT`, `ORBIT`, `RUN`
`get_register`	Read the value of a register on the attached Caribou device	Device name and register name, as `string` values	Register reading, `int`	`INIT`, `ORBIT`, `RUN`
`get_memory`	Read the value of a FPGA memory register on the attached Caribou device	Device name and memory register name, as `string` values	Memory register reading, `int`	`INIT`, `ORBIT`, `RUN`

Framework Parameters#

This satellite inherits the following framework parameters from its base classes:

Parameters inherited from `TransmitterSatellite`#

Parameters to control data transmission in the _data section:

Parameter	Type	Description	Default Value
`bor_timeout`	Unsigned integer	Timeout in seconds to send the BOR message. The satellite will attempt for this interval to send the message and goes into `ERROR` state if it fails to do so. A possible reason for failure is that no receiver satellite connected to this satellite and is receiving data.	10
`eor_timeout`	Unsigned integer	Timeout in seconds to send the EOR message. The satellite will attempt for this interval to send the message and goes into `ERROR` state if it fails to do so.	10
`data_timeout`	Unsigned integer	Timeout in seconds to send the data message. The satellite will attempt for this interval to send the message and goes into `ERROR` state if it fails to do so.	10
`payload_threshold`	Unsigned integer	Threshold for sending data messages in KiB. The satellite will only send queued data records after the combined payload size of the data records has reached this threshold.	128
`queue_size`	Unsigned integer	Size of the queue for the data records. Small values might lead to performance issues, large values lead to larger memory usage.	32768
`license`	String	License this data is recorded under. Defaults to the Open Data Commons Attribution License. This information will be added to the run metadata.	`ODC-By-1.0`

Parameters inherited from `Satellite`#

Autonomous Operation#

Parameters to control autonomy in the _autonomy section:

Parameter	Type	Description	Default Value
`role`	Role name	Role this satellite should take in the Constellation. Accepted values are `ESSENTIAL`, `DYNAMIC`, `TRANSIENT` and `NONE`.	`DYNAMIC`
`max_heartbeat_interval`	Unsigned integer	Maximum interval in seconds between heartbeats to be sent to other Constellation components. The time between heartbeat is adjusted automatically according to the number of nodes in the Constellation but will never exceed this value.	`30`

Conditional Transitions#

Parameters to control conditional transitions in the _conditions section:

Parameter	Type	Description	Default Value
`require_initializing_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `initializing` state	-
`require_launching_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `launching` state	-
`require_landing_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `landing` state	-
`require_starting_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `starting` state	-
`require_stopping_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `stopping` state	-
`transition_timeout`	Unsigned integer	Timeout in seconds to wait for all conditions to be satisfied for conditional transitioning	`30`

Framework Metrics#

This satellite inherits the following framework metrics from its base classes:

Metrics inherited from `TransmitterSatellite`#

Metric	Description	Value Type	Interval
`TX_BYTES`	Amount of bytes transmitted during current run	Integer	10s
`TX_BLOCKS`	Number of data blocks transmitted during current run	Integer	10s
`TX_RECORDS`	Number of data records transmitted during current run	Integer	10s

Metrics inherited from `Satellite`#

Metric	Description	Value Type	Interval
`RUN_ID`	Current run identifier. Updated whenever it changes.	String	-