-
Notifications
You must be signed in to change notification settings - Fork 15
State Machines
This is a brief description of the hexabus state machines as they are implemented in the current development branch.
Set of states, set of transitions, you know the drill...
Conditions, value-dependent transitions and date/time-dependent transitions (only usable when datetime-service is enabled) are stored in seperate areas in the eeprom, and there are data structures for conditions and transitions defined in state_machine.h
Each transition has a condition index, giving the index in the array of conditions in the eeprom. This is intended to save some memory since transitions sharing the same conditions can just point to the same entry in the array. It also has a number of state indices: fromState, the state the machine has to be in in order for the transition to be applicable, goodState and badState (described below). Furthermore, it stores an endpoint ID and a data data structure (a data structure named data, see https://github.com/mysmartgrid/hexabus/issues/38). This is the Action of this transition.
Every transition has an action (set endpoint to value), a goodState and a badState. When the transition is executed, endpoint_write is called with the endpoint ID and the value. If it succeeds (returns 0), the machine goes into the goodState. If it fails (returns something !=0), the machine goes to the badState.
The condition data structure describes the conditions: They consist of a source IP, a source endpoint ID, an operator and a constant (value) to compare with.
All value dependent transitions are checked (and executed when indicated) every time a value broadcast is reveived. The first matching transition is executed.
The operators are =, <=, >=, <, >, != encoded into a 8 bit integer value as defined in state_machine.h
To execute a transition, source IP and source EID have to match. The operator and constant are evaluated, and the transition is executed accordingly.
All date/time-dependent transitions are checked (and execuded if applicable) periodically (every 5 seconds).
The data/time conditions are checked a bit differently. Source IP and EID do not matter since the conditions are checked against the internal clock provided by datetime-service. The operators are used in a different way, as well. op is an 8-bit value. Bits 0..6 are used to denote the different fields of the datetime structure. When a bit is set to 1, the corresponding field is checked: 0x01 stands for hour, 0x02 for minute, 0x04 for second, and so on. (The first bit that matches is used, so setting multiple bits is not useful.) Bit number 7 (0x80) is the operator: The selected field of the date/time struct in the condition is compared to the current date/time. If the bit number 7 is set to 1, the condition evaluates to true if the corresponding field in the current date/time is greater or equal to that in the conditions. When the bit number 7 is set to 0, < is used as the operator.
The state machine keeps track of how long it has remained in its current state by means of a variable called inStateSince and a timestamp provided by the datetime-service (counting seconds since the device was booted up). When a transition stored in the date/time transition table uses the HXB_DTYPE_TIMESTAMP datatype, it is a timestamp transition. The 32bit value it carries is checked against the number of seconds the state-machine has remanined in the fromState. If the op is 0x80 (bit 7 set, all others 0) (this was meant as a means of implementing different operators, but none except >= were deemed useful), the transition is executed iff the machine has remained in the current state for at leas the number of seconds indicated by the condition's value field.
The content of the state machine program eeprom needs to be hardcoded into the state_machine.c (near PROCESS_BEGIN(); See Example state machines to get a more detailed impression.
Every Hexabus device has a simple webserver. If you navigate your browser to the IP of the device, there should be something called "State Machine Configurator" in the navigation bar on the left. Via this WebInterface it is possible to change the state machine code at runtime - however, no validation whatsoever of the input data is performed, so be careful. The configuration form will output a string, formatted in a certain way. The format is as follows:
-ConditionTable.-TransitionTable.
A ConditionTable line looks like this:
SourceIP.SourceEID.DataType.Operator.Value.
a TransitionTable line is very similar:
FromState.Cond#.Eid.DataType.Value.GoodState.BadState.