 |
rasProject_01 / weSweetHome
R. 102 2025-10-31
process control / RasPi software by weinert-automation
|
|
rasProject_01 / weSweetHome
R. 102 2025-10-31
process control / RasPi software by weinert-automation
|
The structure for state machines. More...
#include <weStateM.h>
Data Fields | |
| union { | |
| enterState_t const doEnter | |
| This state machine's function to enter it. More... | |
| enterStateF_t const doEnterF | |
| Float control substitute or addendum to state_t.doEnter. | |
| enterStateS_t const doEnterS | |
| Character control substitute or addendum to state_t.doEnter. | |
| }; | |
| Just one enter function (type). More... | |
| union { | |
| }; | |
| This state machine's function to leave it. More... | |
| union { | |
| }; | |
| This state machine's trigger respectively check function. More... | |
| float | controlF |
| the analogue / float control value (some state types) | |
| uint32_t | controlV |
| the integer control value (most state types) | |
| char | controlVS [8] |
| The control value for the state machine in question. More... | |
| genStateText_t | doGenStateText |
| This state machine's function for status text generation. More... | |
| uint32_t | endTime |
| The end time of a state or sub-state. More... | |
| char | infoTxt [36] |
| state infotext (provided by application software) | |
| uint8_t | instanceB [4] |
| Four byte values to the state machines disposal. More... | |
| float | instanceF [3] |
| Three float values to the state machines disposal. More... | |
| char const | name [22] |
| State machine name. More... | |
| uint8_t const | offChainEnd |
| Length of OFF chain. More... | |
| uint8_t const | onChainEnd |
| Length of ON chain. More... | |
| onStateChange_t const | onStateChange |
| This state machine's callback function for state changes. More... | |
| uint32_t | realSecOff |
| s time stamp of last exit transition | |
| uint32_t | realSecOn |
| s time stamp of last enter transition | |
| uint8_t | status |
| Status number. More... | |
| uint8_t | subStatus |
| Addendum to status for more complicated state machines. More... | |
| float | threshBadLo |
| The bad Lo limit. More... | |
| float | threshCritLo |
| The critical Lo limit. | |
| float | threshOFF |
| The lower or OFF threshold. More... | |
| float | threshON |
| The higher or ON threshold. More... | |
| uint8_t const | typ |
| State machine type. More... | |
The structure for state machines.
The semantics and usage of most fields depends on the type state_t::typ of the state machine and often on concrete implementations (instance).
Fields normally unused by the design of the basic type state_t::typ may, with caution, be used by the code making or using concrete state machines.
| char const name[22] |
State machine name.
The names must be unique within one application and best also within a site as it usually will appear in logs as the only identifier of a state machine.
The maximum length is 20. It is recommended to have all state names the same length in an application or better site if feasible. This gives better readability of state machine logs (see logStateText()).
Our current common value is 12.
| uint8_t const typ |
State machine type.
As of Revision 193 the following types are defined and recognised by genStateText() respectively logStateText(): /code 0xAD: Timer, seconds resolution, UTC stamp 0xDB: switch de-Bounce 0xFF: Float value hysteresis 0x5B: 5 band check ...badLO | critLo | OK | critHi | badHi... 0xFC: sequential Control (SFC) /endcode
| uint8_t const onChainEnd |
Length of ON chain.
With SFCs (typ 0xFC) this (or a greater) subStatus value in ON chain will lead to the stable (1:0) ON state. This value is set finally at SFC construction and can't be changed hence on. I.e, this member can be set just once in the respective constructor macro. This corresponds to a "blank final" object variable in Java.
The same holds for onChainEnd, name and typ.
A value of, e.g., 4 would produce an on chain (0:1)->(0:2)->(0:3)=>(1:0) when not changed in a onStateChange function.
With switch de-Bounce (typ 0xDB) it is the up-counter level to recognise ON.
Other state machines defined so far don't define a use for this member variable. See also offChainEnd
| uint8_t const offChainEnd |
Length of OFF chain.
With SFCs (typ 0xFC) this (or greater) subStatus value in OFF chain will lead to the stable (0:0) OFF state. This value must be set at SFC construction and should not be changed hence on.
A value of, e.g., 8 would produce an off chain (1:6)->(1:7)=>(0:0) when not changed in a onStateChange function.
Trick: Lower parts of the off-chain may be used as a check / stay on state machine, e.g. (1:1)->(1:2)-(1:3)->(1:4)=>(1:1). By setting the substatus to 5 or allowing it to increment to 5 in the example would enter the "real" off chain.
With switch de-bounce (typ 0xDB) it is the down-counter start value to recognise OFF at 0.
Other state machines defined so far don't define a use for this member variable.
| enterState_t const doEnter |
This state machine's function to enter it.
The fitting function to enter this state, respectively to start its transition from OFF to ON might be recorded in and then called via this function pointer.
| union { ... } @4 |
Just one enter function (type).
Any state machine object (instance) will have a distinct final enter function, the type of which is specific for the state machine type. Hence a union over the (currently three) possible function types is well justified.
The same holds for the doLeave and tickCheck types.
Note: Unions of state variables designated for use only in separate types were banned as of Rev. 86. The savings of memory space by those unions were not worth the danger of hard to find errors, when underlying the assumptions were violated.
| union { ... } @6 |
This state machine's function to leave it.
The fitting function to leave this state, respectively to start its transition from ON to OFF might be recorded in and then called via this function pointer.
| union { ... } @8 |
This state machine's trigger respectively check function.
The fitting function to check if a change of state_t.status or state_t.subStatus is due might be recorded in and then called via this function pointer.
| onStateChange_t const onStateChange |
This state machine's callback function for state changes.
The fitting function to be called on a real change of state_t.status and depending on type also on changes of state_t.subStatus must be recorded in this function pointer. In contrast to the other function pointers in this state_t structure, this pointer should not be NULL.
| genStateText_t doGenStateText |
This state machine's function for status text generation.
The default setting will be genStateText().
| uint8_t status |
Status number.
State numbers together with sub state numbers (if applicable) must be unique, and best dense (0..n-1) within a concrete state machine (being in exactly one of n states). Status number 0,0 is reserved for the machine's default / reset / OK state.
State machines with just two (big / first level) states can best be modelled having just one "singleton" state being either On or Off.
timer (AD):
1: (still) running; 0: ended
simple:
0: OFF; else: ON
SFC (FC):
0,0: OFF
0,x: chain to ON
4,x: chain to ON interrupted
1,0: ON
1,x: chain to OFF
5,x: chain to OFF interrupted;
Five band check (5B):
2: bad Hi
1: critical Hi
0: OK (and, hence, here usually ON while 2 and 6 would mean OFF)
5: critical Lo
6: bad Lo
//// 8: unknown / reset
//// subStatus is used as previous state.
| uint8_t subStatus |
Addendum to status for more complicated state machines.
The semantic of subStatus is machine type dependent.
For SFC (FC) it is 0: stable; !=0: internal transitions.
| uint32_t endTime |
The end time of a state or sub-state.
For timers it's the end time of the ON state.
| char controlVS[8] |
The control value for the state machine in question.
This is the recorded control value of the last trigger. Any state machine instance must finally chose one of these three types according to the type of the tick (trigger) function.
The three types are
| float threshOFF |
The lower or OFF threshold.
For five band check (5B) this is the bad Hi limit.
For a float hysteresis (FF) the following inequation
must hold.
| float threshON |
The higher or ON threshold.
For five band check (5B) this is the critical Hi limit.
| float threshBadLo |
The bad Lo limit.
For five band check (5B) the following inequation
must hold.
| float instanceF[3] |
Three float values to the state machines disposal.
| uint8_t instanceB[4] |
Four byte values to the state machines disposal.
Currently (10.2025) only [2] and [3] used.
1.9.5