StatusObjects

Inheritance diagram of automate.statusobject.StatusObject, automate.statusobject.AbstractSensor, automate.statusobject.AbstractActuator

Actuators (AbstractActuator) and sensors (AbstractSensor) are subclassed of StatusObject. The most important property is status, which may be of various data types, depending of the implementation defined in subclasses. Type of status is determined by _status trait.

There are couple of useful features in StatusObjects that may be used to affect when status is really changed. These are accessible via the following attributes:

  • safety_delay and safety_mode can be used to define a minimum delay between status changes (“safety” ~ some devices might break if changed with big frequency)
  • change_delay and change_mode can be used to define a delay which (always) takes place before status is changed.

Here, modes are one of 'rising', 'falling', 'both', default being 'rising'. To disable functionality completely, set corresponding delay parameter to zero. Functions are described below.

Creating Custom Sensors and Actuators

Custom actuators and sensors can be easiliy written based on AbstractActuator and AbstractSensor classes, respectively.

As an example, we will define one of each:

# imports from your own library that you are using to define your sensor & actuator
from mylibrary import (setup_data_changed_callback,
                       fetch_data_from_my_datasource,
                       initialize_my_actuator_device,
                       change_status_in_my_actuator_device)

class MySensor(AbstractSensor):
   """
   Let us assume that you have your own library which has a status that you
   want to track in your Automate program.
   """
   # define your status data type
   _status = CBool
   def setup(self):
       setup_my_datasource()
       # we tell our library that update_status need to be called when status is
       # changed. We could use self.set_status directly, if library can pass
       # new status as an argument.
       setup_data_changed_callback(self.update_status)
   def update_status(self):
       # fetch new status from your datasource (this function is called by
       # your library)
       self.status = fetch_data_from_your_datasource()
   def cleanup(self):
       # define this if you need to clean things up when program is stopped
       pass

class MyActuator(AbstractActuator):
   # define your status data type. Transient=True is a good idea because
   # actuator status is normally determined by other values (sensors & programs etc)
   _status = CFloat(transient=True)
   def setup(self):
       initialize_my_actuator_device()
   def _status_changed(self):
       chagnge_status_in_my_actuator_device(self.status)

For more examples, look builtin_sensors and builtin_actuators. For more examples, see also Extensions, especially support modules for Arduino and Raspberry Pi IO devices)

StatusObject Definition

class automate.statusobject.StatusObject(*args, **kwargs)[source]

Baseclass for Sensors and Actuators

safety_delay = None

Determines minimum time required for switching. State change is then delayed if necessary.

safety_mode = None

Determines when safety_delay needs to be taken into account: when status is rising, falling or both.

change_delay = None

Similar to safety_delay, but just delays change to make sure that events shorter than change_delay are not taken into account

change_mode = None

As safety_mode, but for change_delay

silent = None

Do not emit actuator status changes into logs

debug = None

Print more debugging information into logs

changing = None

(property) Is delayed change taking place at the moment?

is_program

A property which can be used to check if StatusObject uses program features or not.

status = None

Status of the object.

get_status_display(**kwargs)[source]

Define how status is displayed in UIs (add units etc.).

get_as_datadict()[source]

Get data of this object as a data dictionary. Used by websocket service.

set_status(new_status, origin=None, force=False)[source]

For sensors, this is synonymous to:

sensor.status = new_status

For (non-slave) actuators, origin argument (i.e. is the program that is changing the status) need to be given,

update_status()[source]

In sensors: implement particular value reading from device etc. here (this calls set_status(value)). In actuators: set value in particular device. Implement in subclasses.

activate_program(program)[source]

When program controlling this object activates, it calls this function.

deactivate_program(program)[source]

When program controlling this object deactivates, it calls this function.

get_program_status(program)[source]

Determine status of this object set by a particular program. Useful only for Actuators but defined here for interface compatibility.

Sensor Baseclass Definition

Inheritance diagram of automate.statusobject.AbstractSensor
class automate.statusobject.AbstractSensor(*args, **kwargs)[source]

Base class for all sensors

user_editable = None

Is sensor user-editable in UIs. This variable is meant for per-instance tuning for Sensors, whereas editable is for per-class adjustment.

default = None

Default value for status

reset_delay = None

If non-zero, Sensor status will be reset to default after defined time (in seconds).

silent = None

Do not log status changes

set_status(status, origin=None, force=False)[source]

Compatibility to actuator class. Also SetStatus callable can be used for sensors too, if so desired.

update_status()[source]

A method to read and update actual status. Implement it in subclasses, if necessary

Actuator Baseclass Definition

Inheritance diagram of automate.statusobject.AbstractActuator
class automate.statusobject.AbstractActuator(*args, **kwargs)[source]

Base class for all actuators.

default = None

Default value for status. For actuators, this is set by automatically created DefaultProgram dp_actuatorname

slave = None

If True, actual status can be set by any program anytime without restrictions.

program = None

A property giving current program governing the status of this actuator (program that has the highest priority)

priorities = None

This dictionary can be used to override program priorities.

Note

Keys here must be program names, (not Program instances).

default_program = None

Reference to actuators DefaultProgram

set_status(status, origin=None, force=False)[source]

For programs, to set current status of the actuator. Each active program has its status in program_stack dictionary and the highest priority is realized in the actuator

activate_program(program)[source]

Called by program which desires to manipulate this actuator, when it is activated.

deactivate_program(program)[source]

Called by program, when it is deactivated.

update_program_stack()[source]

Update program_stack. Used by programs _priority_changed attribute to reset ordering.

get_program_status(prog)[source]

Give status defined by given program prog

program_stack = None

Program stack of current programs, sorted automatically by program priority.

program_status = None

Dictionary containing statuses set by each active program