device - Device abstraction

pycstbox.hal.device.log_setLevel(level)

Set the level of module level logging.

pycstbox.hal.device.DEFAULT_PRECISION = 3

Default precision for notified values.

class pycstbox.hal.device.HalDevice(coord, cfg)

Base class for modeling devices in the abstraction layer.

It acts as a kind of driver and is responsible for interfacing the real equipments with the generic communication layer.

This base class includes the generic mechanism which produces CSTBox events based on data produce by the equipment outputs (see create_events()), and can be used as is for modeling asynchronous equipments which produce data on their own (ie without being polled).

Polled devices are modeled by the PolledDevice class, which provides the foundation for managing the dialog with the physical equipment in order to get its outputs.

Parameters:
  • coord (Coordinator) – the parent coordinator
  • cfg (dict) – the device configuration, as retrieved from the global configuration data
is_pollable()

Tells if the device can be polled.

Polled equipments HalDevice sub-classes must provide a method named “poll”, which takes no parameter and returns the list of CSTBox events reflecting the reply to the poll request.

The returned events must be instances of pycstbox.events.BasicEvent or pycstbox.events.TimedEvents.

The poll method must notify any error by raising a PollingError exception.

create_events(output_values)

Creates the list of events depending on the collected or received data from the device.

This method takes care of handling the filtering of redundant events (same value received again and again), based of device settings such as the events time to live.

Same for filtering small variations of the values.

It relies on the method get_output_data_definition(), which must be implemented by subclasses to provide the value type and unit associated to a given device output. These information are used to build the event to be produced.

Parameters:output_values (tuple) – a tuple containing the values produced by the output(s) of the device. Output values set to None are silently ignored
Returns list:a (possibly empty) list of events to be emitted
classmethod get_output_data_definition(output)

Returns the type of the data and its units (if any) for a given output.

“type of the data” is taken at the semantic level, not at computer language level. It can be something like “temperature”, “voltage”,...

The _OUTPUTS_TO_EVENTS_MAPPING attribute is initialized at initialization time of the HAL, using the introspection mechanism based on the pycstbox.hal.hal_device() decorator.

Parameters:output (str) – the name of the output
Returns:a tuple composed of:
  • the type of the data
  • the units (if any)
class pycstbox.hal.device.EventDataDef(var_type, units)

Named tuple describing the data to be conveyed by sensor notification events

Key var_type:type of the variable which change is notified by the event
Key units:units used for the value
units

Alias for field number 1

var_type

Alias for field number 0

class pycstbox.hal.device.PolledDevice(coord, cfg)

A device which works by polling and not spontaneaous notification.

This class adds the method poll() which takes care of:

  • invoking the low level interface (self._hwdev) for querying the values. The device implementation classes can do it on their own if they can, or rely to the send_device_command() method provided by a specialized coordinator class
  • translating the received values into the corresponding collection of events to be broadcasted by calling the super-class create_events() method

Important

This class cannot be used as is for implementing devices, but must be sub-classed to add in its initialization code the connection with an object responsible for the low-level interactions with the equipment. This connection is established by initializing the private attribute _hwdev with and instance of an object implementing a ``poll` method. Proper initialization is checked at first poll time, and the device will be tagged as invalid (and will be no more polled) if not compliant.

Refer to pycstbox.hal.device.HalDevice for parameters definition.

poll()

Refer to pycstbox.hal.device.HalDevice for details.

exception pycstbox.hal.device.PollingError(dev_id, error)

Specialized exception for polling errors.

Parameters:
  • dev_id (str) – id of the device being polled
  • error (Exception) – reported error