peary::device::Device link

Abstract Caribou Device class definition. More…

#include <peary/device/Device.hpp>

Inherited by peary::device::AuxiliaryDevice< T >, peary::device::CaribouDevice< B, SCI, DRI >

Public Functions link

Protected Attributes link

Friends link

Detailed Description link

  class peary::device::Device;
  

Abstract Caribou Device class definition.

This is the central device class from which all device implementations inherit. Some basic functionality is defined via purely virtual member functions which have to be implemented by every device instance. This enables the possibility of interfacing the devices independently via the common set of function calls, e.g., from a GUI or a commandline interface.

Public Functions Documentation link

function Device link

  explicit Device(
    const config::Configuration & 
)
  

Default constructor for Caribou devices.

function ~Device link

  virtual ~Device()
  

Default destructor for Caribou devices.

function isManaged link

  inline bool isManaged()
  

Indicator flag for managed devices.

Return: True if managed, false if unmanaged

function getVersion link

  std::string getVersion()
  

Return the software version string for reference.

Peary software version string

function getFirmwareVersion link

  virtual std::string getFirmwareVersion() =0
  

Return the version string of the firmware currently loaded.

Return: Firmware version string

Reimplemented by: peary::device::AuxiliaryDevice::getFirmwareVersion, peary::device::CaribouDevice::getFirmwareVersion

function getName link

  virtual std::string getName() =0
  

Return the human-readable device name (full qualifier)

Return: Device name

Reimplemented by: peary::device::AuxiliaryDevice::getName, peary::device::CaribouDevice::getName

function getType link

  virtual std::string getType() =0
  

Return the device type, derived from the class name.

Return: Device type

Reimplemented by: peary::device::AuxiliaryDevice::getType, peary::device::CaribouDevice::getType

function powerOn link

  virtual void powerOn() =0
  

Turn on all registered power supplies for the device.

Reimplemented by: peary::device::AuxiliaryDevice::powerOn, peary::device::CaribouDevice::powerOn

function powerOff link

  virtual void powerOff() =0
  

Turn off all registered power supplies for the device.

Reimplemented by: peary::device::AuxiliaryDevice::powerOff, peary::device::CaribouDevice::powerOff

function daqStart link

  virtual void daqStart() =0
  

Start data acquisition mode.

Reimplemented by: peary::device::AuxiliaryDevice::daqStart, peary::device::CaribouDevice::daqStart

function daqStop link

  virtual void daqStop() =0
  

Stop data acquisition mode.

Reimplemented by: peary::device::AuxiliaryDevice::daqStop, peary::device::CaribouDevice::daqStop

function getRawData link

  virtual utils::pearyRawData getRawData() =0
  

Retrieve raw data from the device.

Exceptions:

• NoDataAvailable exceptions if no data is there

Return: Raw detector data

Reimplemented by: peary::device::AuxiliaryDevice::getRawData, peary::device::CaribouDevice::getRawData

This data is a vector of pearyRawDataWord_type words of undecoded detector response. Peary does not make any assumption on the content or structure, and special decoders have to be provided in order to decode and interpret this data. This is the method to be used by integrated data acquisition systems such as EUDAQ to retrieve data from the attached detector without the requirement of knowing which exact device it is.

function getRawData link

  virtual utils::pearyRawDataVector getRawData(
    const unsigned int noFrames
) =0
  

Retrieve number of raw data frames from the device.

Parameters:

• noFrames Number of frames to read

Exceptions:

• NoDataAvailable exceptions if no data is there

Return: Vector of raw detector data frames

Reimplemented by: peary::device::AuxiliaryDevice::getRawData, peary::device::CaribouDevice::getRawData

This data is a vector of pearyRawData fames of undecoded detector response. Peary does not make any assumption on the content or structure, and special decoders have to be provided in order to decode and interpret this data. This is the method to be used by integrated data acquisition systems such as EUDAQ to retrieve data from the attached detector without the requirement of knowing which exact device it is.

function getData link

  virtual utils::pearydata getData() =0
  

Retrieve decoded data from the device.

Exceptions:

• NoDataAvailable exceptions if no data is there

Return: Decoded detector data

Reimplemented by: peary::device::AuxiliaryDevice::getData, peary::device::CaribouDevice::getData

This method is designed for immediate quality checks of the data. Each device has to implement a decoder to translate their own data into a readable format. For this propose, the utils::pearydata data type is used, which is a map of pixel coordinates and unique pointers to pixel objects. These pixel objects can be overloaded by the device to store relevant information. The method can also be used to e.g. write decoded data directly into an ASCII file.

function getData link

  virtual utils::pearydataVector getData(
    const unsigned int noFrames
) =0
  

Retrieve number of decoded data frames from the device.

Exceptions:

• NoDataAvailable exceptions if no data is there

Return: Vector of decoded detector data

Reimplemented by: peary::device::AuxiliaryDevice::getData, peary::device::CaribouDevice::getData

This method is designed for immediate quality checks of the data. Each device has to implement a decoder to translate their own data into a readable format. For this propose, the utils::pearydata data type is used, which is a map of pixel coordinates and unique pointers to pixel objects. These pixel objects can be overloaded by the device to store relevant information. The method can also be used to e.g. write decoded data directly into an ASCII file.

function configure link

  virtual void configure() =0
  

Configure the device.

Reimplemented by: peary::device::AuxiliaryDevice::configure, peary::device::CaribouDevice::configure

Initialize the device (ex.set the required clock otuputs etc.). This function is part of the standard “booting” sequence for any device and should be called by programs using the Peary library for cdevice communication. Among other settings, it configures the with all DACs to the values provided via the initial configuration object passed to the device constructor.

function setRegister link

  virtual void setRegister(
    std::string name,
    uintptr_t value
) =0
  

Set register on the device.

Parameters:

• name Name of the register
• value Value to be programmed

Exceptions:

• ConfigInvalid if the register name is not valid
• RegisterTypeMismatch if the register is not writable
• CommunicationError if the device could not be contacted

Reimplemented by: peary::device::CaribouDevice::setRegister, peary::device::AuxiliaryDevice::setRegister

The register is identified by its human-readable name using the register dictionary, its value is automatically casted to the register data type (e.g. 8-bit). The device has to provide a list of valid register names.

function getRegister link

  virtual uintptr_t getRegister(
    std::string name
) =0
  

Get register from the device.

Parameters:

• name Name of the register

Exceptions:

• ConfigInvalid if the register name is not valid
• RegisterTypeMismatch if the register is not readable
• CommunicationError if the device could not be contacted

Return: Value of the register

Reimplemented by: peary::device::CaribouDevice::getRegister, peary::device::AuxiliaryDevice::getRegister

Retrieve content of specified register from the device. The register is identified by its human-readable name via the register dictionary.

function getRegisters link

  virtual std::vector< std::pair< std::string, uintptr_t > > getRegisters() =0
  

Get list of all readable registers with their current values.

Return: Vector with pairs of register name and value

Reimplemented by: peary::device::AuxiliaryDevice::getRegisters, peary::device::CaribouDevice::getRegisters

This method internally calls device::getRegister for every known register of the device. Only readable registers are returned and no exception is thrown when attempting to read write-only registers.

function reset link

  virtual void reset() =0
  

Send reset signal to the device.

Reimplemented by: peary::device::AuxiliaryDevice::reset, peary::device::CaribouDevice::reset

function setVoltage link

  virtual void setVoltage(
    const std::string & name,
    double voltage
) =0
  

Set voltage and current limit on the board components.

Parameters:

• name Name of the component
• voltage Voltage to be set in V

Reimplemented by: peary::device::AuxiliaryDevice::setVoltage, peary::device::CaribouDevice::setVoltage

This method allows to configure voltage regulators, bias voltages and injection pulser voltages

function setCurrentLimit link

  virtual void setCurrentLimit(
    const std::string & name,
    double current_limit
) =0
  

Set voltage and current limit on the board components.

Parameters:

• name Name of the component
• current_limit current limit to be set in A

Reimplemented by: peary::device::AuxiliaryDevice::setCurrentLimit, peary::device::CaribouDevice::setCurrentLimit

This method allows to configure voltage regulators, bias voltages and injection pulser voltages

function switchOn link

  virtual void switchOn(
    const std::string & name
) =0
  

Switch on the given board resource.

Parameters:

• name Name of the resource

Reimplemented by: peary::device::AuxiliaryDevice::switchOn, peary::device::CaribouDevice::switchOn

This method allows to switch on individual resources on the board such as power supplied or biad voltages. The resource is identified by its human-readable name and has to be registered by the device in the periphery dictionary

function switchOff link

  virtual void switchOff(
    const std::string & name
) =0
  

Switch off the given board resource.

Parameters:

• name Name of the resource

Reimplemented by: peary::device::AuxiliaryDevice::switchOff, peary::device::CaribouDevice::switchOff

This method allows to switch off individual resources on the board. The resource is identified by its human-readable name and has to be registered by the device in the periphery dictionary.

function setCurrent link

  virtual void setCurrent(
    const std::string & name,
    double current,
    utils::Polarity polarity
) =0
  

Configure board current source.

Parameters:

• name Name of the current source
• current Current to be set in A
• polarity Polarity of the source, true: PUSH, false: PULL

Reimplemented by: peary::device::AuxiliaryDevice::setCurrent, peary::device::CaribouDevice::setCurrent

function getVoltage link

  virtual double getVoltage(
    const std::string & name
) =0
  

Get voltage of the given board resource.

Parameters:

• name Name of the resource

Return: Voltage in V

Reimplemented by: peary::device::AuxiliaryDevice::getVoltage, peary::device::CaribouDevice::getVoltage

function getCurrent link

  virtual double getCurrent(
    const std::string & name
) =0
  

Get current from the given board resource.

Parameters:

• name Name of the resource

Return: Current in A

Reimplemented by: peary::device::AuxiliaryDevice::getCurrent, peary::device::CaribouDevice::getCurrent

function getPower link

  virtual double getPower(
    const std::string & name
) =0
  

Get power consumption of the given board resource.

Parameters:

• name Name of the resource

Return: Power in W

Reimplemented by: peary::device::AuxiliaryDevice::getPower, peary::device::CaribouDevice::getPower

function configureClock link

  virtual void configureClock(
    const std::string & name,
    const std::any & config
) =0
  

Configure a clock output on the board.

Parameters:

• name Name of the resource
• config Configuration object for the clock

Reimplemented by: peary::device::AuxiliaryDevice::configureClock, peary::device::CaribouDevice::configureClock

function disableClock link

  virtual void disableClock(
    const std::string & name
) =0
  

Disable a clock output on the board.

Parameters:

• name Name of the resource

Reimplemented by: peary::device::AuxiliaryDevice::disableClock, peary::device::CaribouDevice::disableClock

function isClockLocked link

  virtual bool isClockLocked(
    const std::string & name
) =0
  

Check if a clock output is locked.

Parameters:

• name Name of the resource

Return: True if the clock is locked, false otherwise

Reimplemented by: peary::device::AuxiliaryDevice::isClockLocked, peary::device::CaribouDevice::isClockLocked

function setClockFrequency link

  virtual void setClockFrequency(
    const std::string & name,
    uint64_t frequency
) =0
  

Set frequency of a clock output on the board.

Parameters:

• name Name of the resource
• frequency Frequency in Hz

Reimplemented by: peary::device::AuxiliaryDevice::setClockFrequency, peary::device::CaribouDevice::setClockFrequency

function setMemory link

  virtual void setMemory(
    const std::string & name,
    size_t offset,
    uintptr_t value
) =0
  

Set memory register on this device.

Parameters:

• name Name of the memory register
• offset Offset to be applied to the base address of the memory register
• value Value to be set

Reimplemented by: peary::device::AuxiliaryDevice::setMemory, peary::device::CaribouDevice::setMemory

function setMemory link

  virtual void setMemory(
    const std::string & name,
    uintptr_t value
) =0
  

Set memory register on this device.

Parameters:

• name Name of the memory register
• value Value to be set

Reimplemented by: peary::device::AuxiliaryDevice::setMemory, peary::device::CaribouDevice::setMemory

function getMemory link

  virtual uintptr_t getMemory(
    const std::string & name,
    size_t offset
) =0
  

Get memory register from this device.

Parameters:

• name Name of the memory register
• offset Offset to be applied to the base address of the memory register

Reimplemented by: peary::device::AuxiliaryDevice::getMemory, peary::device::CaribouDevice::getMemory, peary::device::CaribouDevice::getMemory

function getMemory link

  virtual uintptr_t getMemory(
    const std::string & name
) =0
  

Get memory register from this device.

Parameters:

• name Name of the memory register

Reimplemented by: peary::device::AuxiliaryDevice::getMemory, peary::device::CaribouDevice::getMemory, peary::device::CaribouDevice::getMemory

function getMemories link

  virtual std::vector< std::pair< std::string, uintptr_t > > getMemories() =0
  

Get list of all readable memory registers with their current values.

Return: Vector with pairs of memory register name and value

Reimplemented by: peary::device::AuxiliaryDevice::getMemories, peary::device::CaribouDevice::getMemories

This method internally calls device::getMemory for every known memory register. Only readable registers are returned and no exception is thrown when attempting to read write-only registers.

function listMemories link

  virtual std::vector< std::string > listMemories() =0
  

List all memory registers.

Return: Vector with names of all available memory pages

Reimplemented by: peary::device::AuxiliaryDevice::listMemories, peary::device::CaribouDevice::listMemories

List all memory registers (accessed through memory pages mapping) known to this device

function listRegisters link

  virtual std::vector< std::string > listRegisters() =0
  

List all registers known to this device.

Return: Vector with names of all available registers

Reimplemented by: peary::device::AuxiliaryDevice::listRegisters, peary::device::CaribouDevice::listRegisters

function listResources link

  virtual std::vector< std::pair< std::string, std::string > > listResources() =0
  

List all periphery components and their types registered by this device.

Return: Vector with pairs of component name and component type

Reimplemented by: peary::device::AuxiliaryDevice::listResources, peary::device::CaribouDevice::listResources

function listCommands link

  std::vector< std::pair< std::string, std::size_t > > listCommands()
  

Retrieve list of all available device-specifiv commands.

Return: List of available commands as pair of command name and number of expected arguments

function command link

  std::string command(
    const std::string & name,
    const std::vector< std::string > & args =std::vector< std::string >()
)
  

Call device-specific command with a list of arguments.

Exceptions:

• ConfigInvalid if command is not found or number of arguments does not match

Return: String containing the return value of the command

function command link

  std::string command(
    const std::string & name,
    const std::string & arg
)
  

Call device-specific command with a single argument.

Return: String containing the return value of the command

Protected Attributes Documentation link

variable _dispatcher link

  utils::Dispatcher _dispatcher;
  

Command dispatcher for this device.

Allows to register commands and calls to be routed to child class member functions. This member is protected and derived classes have direct access to it in order to register their own commands.

Friends link

friend DeviceManager link

  friend class DeviceManager(
    DeviceManager 
);
  

Updated on 2025-11-14 at 11:31:23 +0100