statemgr - State variables management

Note

At the time of writing, this module is not integrated in the core by default, although it is intended to. It is thus distributed as a separate installation package during the transitional period.

State variables are the interface used to interact with the observed and/or controlled system (a house, an office building, an experiment,...) from the application layer.

Its purpose is to fully decouple the application processes from the physical nature of the instrumentation of the system, be it sensors, actuators,... This is achieved by defining a state vector with gathers all the parameters which are used for monitoring and control the target system, these parameters being modeled as state variables.

State variables are classified in two categories :

observation variables
The are read-only and represent live values of measured parameters. They will most of the time been updated by readings received from deployed sensors.
control variables
They are changed by the application layer and monitored by the hardware abstraction layer (which the statevars package is part of) to send the appropriate commands the the involved physical equipments.

State variable are semantically typed, which means that their definition specifies the semantic type (a temperature, a pressure, a voltage, a count,...) they are an instance of. In addition, the definition of a given variable specifies which units (among the valid ones for the underlying semantic type) it uses for its value, and can specify a set of validity rules, such as absolute bounds, variation bounds, derivative bounds,... or any other custom rule which can be defined by the application and attached to the variable.

Semantic types are themselves predefined, to specified shared properties such as acceptable units, validity domain of the values,...

The state variable management package is composed of several modules, documented hereafter:

  • core : the core definitions
  • mgr : the manager layer, built on top of core
  • dbus_binding : binding of the manager with D-Bus

statemgr.core

Definitions of the types used by the state manager.

The core concepts are :

  • the state vector, composed of a list of state variables

  • the state variable, holding the current value of an observed parameter, or

    of a device command or setting

  • the type definition, which is used by state variables for specifying the kind

    of information they convey, their domain validity,...

class pycstbox.statemgr.core.StateVector

A collection of state variables, used to observe and control a complex system.

It mimics a typed dictionary, keyed by the name of the variable, gathering all the registered variables (kind of symbol tables used by compilers folks).

For convenience sake, the values of the variables are directly accessed as if they were first level items of the vector. This allows writing :

>>> vector['my_var'] = 42

instead of :

>>> vector['my_var'].value = 42

for updating a value. An additional benefit is that the existence of the variable is checked when its value is accessed and raises a KeyError exception if it has not been previously added to the vector, using add_variable() method.

add_variable(state_var)

Add a new variable to the vector

The name of the variable must match to common syntax rules used in programming languages. This is checked on input.

The passed state variable be an instance of either ObservationVariable or ControlVariable.

Adding an existing variable raises an exception.

Parameters:or ControlVariable state_var (ObservationVariable) – the state variable to be registered
Raises:AlreadyExists: if the name is already used
Raises:ValueError: if the name does not match the allowed syntax
Raises:TypeError: if the passed state variable parameter is not of the accepted classes
get_variable_definition(name)

Returns the definition of a given variable. :param str name: the name of the variable :return: its definition (if exists) :raises: KeyError: if the variable does not exist.

exception pycstbox.statemgr.core.AlreadyExists

Specialized exception risen when an attempt is made to add an already declared variable to a state vector.

The exception message is the name of the offending variable.

class pycstbox.statemgr.core.StateVariable(var_def)

A state variable.

Holds the current state of a variable and refers to a variable definition. By default, the StateVariable value cannot be modified (the value property is read-only).

class pycstbox.statemgr.core.ObservationVariable(var_def)

Sub-class of StateVariable for read-only variables associated to sensors or similar data sources.

class pycstbox.statemgr.core.ControlVariable(var_def)

Sub-class of StateVariable for read-write variables associated to actuation control.

Adds the write access to the variable value.

class pycstbox.statemgr.core.VariableDefinition(name, type_def, label=None, descr=None, unit=None, readonly=True, rules=None)

The definition of a state variable.

Its core attributes are :

  • the name
  • the type definition
  • the label (short text to be used for UI or reports for instance)
  • the description (explanatory text, for documentation or UI help)
  • the access mode (writable or not)
  • the validity rules if any
class pycstbox.statemgr.core.TypeDefinition(semantic_type, rules=None)

Definition of a variable type.

Its core attributes are :

  • the semantic type (ex: temperature, pressure,...)
  • the allowed units for expressing its value
  • the data type of its value (float, integer, boolean, string).
  • the validity rules to be applied whatever is the variable referencing this type

The type_meta parameter can be either a type name or a TypeMeta instance.

If it is a name, it must be defined in the TypeDefinition.BUILTIN_SEMANTIC_TYPES dictionary. In case of need, this dictionary can be extended by client modules before creating any instance of the :py:class`TypeDefinition` class, using the register_type() method.

Parameters:
  • or type_meta semantic_type (str) – the semantic type of the variable
  • rules (list) – optional rules for validating values
Returns:

statemgr.mgr

statemgr.dbus_binding

class pycstbox.statemgr.dbus_binding.StateManagerSO(conn, mgr)

This class presents a variables state manager as a D-Bus service.

Parameters:
  • conn (Connection) – D-Bus connection (see service.SimpleService.__init__())
  • mgr (StateManager) – the state manager
start()

Service object runtime initialization.

stop()

Cleanup before stop

reload()

Reload the state data from disk

clear()

Clears the in-memory and the persisted state data.

update_variable(name, value)

Update a variable.

Parameters:
  • name (str) – the name of the updated variable
  • value – its value
get_variable(name)

Returns the current value of a given state variable.

Parameters:

name (str) – the name of the requested variable
Returns:

the current state of matching variable(s), returned as a variant
Raises:
  • ValueError – if no variable name is provided
  • KeyError – if variable name does not exist