herosdevices.core - Heros Devices 0.5.5 documentation

Skip to content
Back to top
View this page

# herosdevices.core

Includes core functionalities relevant to all/many hardware driver implementations.

## Submodules

- herosdevices.core.bus
- herosdevices.core.gpio
- herosdevices.core.templates

## Package Contents

herosdevices.core.FieldType

herosdevices.core.any__new__(cls, *_args, **_kwargs) → Any

  Monkey patch for https://github.com/python/cpython/pull/117111.

  Debian and Ubuntu (and possibly other distros with a slow release cycle) ship a version of python with the aforementioned bug.

class herosdevices.core.DeviceCommandQuantity(command_set: str | None = None, command_get: str | None = None, return_check: None | str = None, unit: str = '', dtype: type[FieldType] | None = None, format_fun: collections.abc.Callable[[str], Any] = lambda x: ..., value_check_fun: collections.abc.Callable[[Any], bool | str] = lambda _: ..., poll_interval_limit: float = 1.0, transform_fun: collections.abc.Callable[[Any, bool], Any] = lambda x, _=False: ..., read_line: bool = True)

  Bases: `Any`, `Generic`[`FieldType`]

  Descriptor for attaching getting/setting configuration of hardware directly to class attributes exposed to HEROs.

  This class provides functionality to define a class attribute of the host object based on certain set and get commands of a device on a given interface. Defining an attribute this way makes it directly accessible to HEROS.

  Parameters:

    - command_set – Command to send to the remote device to set the quantity. Must include a single input

    - set. (placeholder in f-string format for the value to be)

    - command_get – Command to send to the remote device to get the quantity.

    - return_check – Return value to check for success

    - unit – Unit of the quantity.

    - dtype – Data type of the quantity values.

    - format_fun – Function to format the raw device return value to obtain the quantity in the correct unit. For example if the device returns a complicated string, this function could use a regex to extract the target value.

    - value_check_fun – Function to check if a set value is valid. Can be used in combination with for example :py:func:`herosdevices.core.utils.limits to check if the value is within a certain range.

    - poll_interval_limit – When getting the value of this quantity, the value is only read from the device if the last read operation was longer ago than the value of `poll_interval_limit`. If it is shorter, the cached value is returned.

    - read_line – If true, the value is read from the device as a single line until the line termination set in the device connection occurs. If false, all waiting data is read, this is typically slower as one needs a longer delay, however it must be used if the return value is multiline.

  Info:

    The host instance must provide `read()->str` and `write(message: str, read_echo: bool) -> None | str` methods. For an example implementation see `herosdevices.core.templates.serial.SerialDeviceTemplate`.

  Warning

  This mechanism stores values in the device object with the name `instance._{attr_name}` and `_{attr_name}_last_poll`, where attr_name is the class attribute name (frequency in the example below). This means you can not implement attributes with these names in you device driver class.

  Example

      class SomeRFSource(RFSource):
          frequency = DeviceCommandQuantity(
              command_set="f{:.3f}",
              command_get="f?",
              dtype=float,
              unit="base",
              value_check_fun=limits(12.5e6, 5.4e9),
              transform_fun=transform_unit("base", "MHz"),
              format_fun=lambda x: float(x)*1e-3,
          )  # Frequency in Hz

  command_set = None
  command_get = None
  return_check = None
  unit = ''
  dtype = None
  format_fun
  value_check_fun
  poll_interval_limit = 1.0
  transform_fun
  read_line = True