events - Basic definitions and tools related to CSTBox events

Basic definitions and tools related to CSTBox events.

The instrumented environment (home, office, experiment,...) is represented by a set of state and control variables. State variables containts the last known value of a given sensor by instance, the current position of an actuator,... while control variables are used to modify the state of an actuator, and thus can represent its set point (ex: the status of a light switch). As a generalization, a control variable can be used to set a message to be displayed on a device, to be vocalized by an audio system, or to be sent as an SMS to a phone number.

A special case of state variable without a value exists for notifications, such as the ones provided by motion sensors. In this case, the event is used to signal that a motion is detected, but does not convey any value (kind of Dirac function).

Basic events are composed of the following parts :

  • a variable type (ex: temperature)
  • a variable name
  • a dictionary containing event data if any, such as the value for events conveying one

(*) the dictionary must be included, and can be empty if the event has no data

Timed events add a time stamp field to these ones. The time stamp is expressed as the number of milliseconds elapsed since the Epoch.

It must be noted that a state variable and a control variable can share the same variable type. There will be no clash since the associated events will be exchanged on distinct channels. This is by the way coherent with respect to what variables represent. For instance, a temperature is always a temperature, no matter if it is the temperature of a given room returned by a sensor, or the set point for a temperature regulator.

Although not a good practice, variable names must be unique within the same type, and only the association (type, name) must be unique. For instance, on can have two variables named “living_room”, one defined with the “temperature” type, and the other with the “movement” one.

BEWARE: since this can lead to unclear configurations, this behaviour is subject to be modified in the future to adopt the approach commonly used for programming languages (ie identifiers uniqueness)

At implementation level, events are conveniently manipulated as tuples, which components are the ones listed above. Python tuples are an efficient and light weight representation allowing to manipulate data as a structured and immutable entity.

For convenience, named tuples are also defined here, conveying explicitly the name of the event components, and ensuring that the components sequence is respected in the tuple.

class pycstbox.events.VarTypes

Common variable types used in events.

class pycstbox.events.DataKeys

Common key names used in the data part of events.

class pycstbox.events.BasicEvent

Undated event conveying a state or value change of a given variable.

Contained attributes:
  • var_type: (str) semantic type of the associated variable
  • var_name: (str) associated variable name
  • data: (dict) dictionary containing the variable properties, including its value, its units if any,....
class pycstbox.events.TimedEvent

Time stamped event, extending the BasicEvent type.

The timestamp is stored as a UTC datetime.datetime.

pycstbox.events.make_data(value=None, units=None, **kwargs)

Builds the data dictionary of an event, handling common items such as the variable value and units if provided.

Parameters:
  • value – the variable value to be integrated in the resulting dictionary
  • units (str) – the variable units to be integrated in the resulting dictionary
  • kwargs – optional named parameters to be added to the dictionary
Returns:

the dictionary containing the passed information
pycstbox.events.make_basic_event(var_type, var_name, value=None, units=None, **kwargs)

Returns a BasicEvent built with the provided pieces.

The return event is used to signal a value change of a variable, or to control an equipment by sending it the new setting of one of its control variables.

Parameters:
  • var_type (str) – the type of the variable
  • var_name (str) – the name of the variable
  • value – (optional) the value of the variable if relevant
  • units (str) – (optional) the units of the variable value
  • kwargs – optional named parameters to be added to the dictionary
Returns:

the corresponding BasicEvent instance
pycstbox.events.make_timed_event(ts, var_type, var_name, value=None, units=None, **kwargs)

Same as make_basic_event, but for a TimedEvent.

The accepted timestamp can be either a datetime.datetime or a msecs count (such as in raw D-Bus transported events).

Parameters:ts – the event timestamp (see make_basic_event() for the other parameters)
Returns:the corresponding TimeEvent instance