 |
API
|
|
|
API
|
|
The MagAO-X stateRuleEngine application. More...
Modules | |
| StateRuleEngine_files | |
Classes | |
| class | MagAOX::app::stateRuleEngine |
| The MagAO-X stateRuleEngine. More... | |
The MagAO-X stateRuleEngine application.
stateRuleEngine is designed to provide a system for evaluating the state of an XWCTk system to provide user feedback when the system is not in the correct state for observations.
Suppose we want to caution the user when the FPM wheel is in a certain position and the focus stage is not in the corresponding position to produce an in-focus image. Recall that information about the instrument is stored in INDI properties, with the logical structure device.property.element=value. We can set up a "rule" to notify the user of this out-of-focus state by creating comparisons between such properties as follows.
First we create a rule to test if fwfpm is in the fpm position:
This rule will evaluate to true whenever the "switch" property element fwfpm.filtername.fpm is in state On. This shows that a rule is named by its TOML section heading, and rules have types specified by the ruleType keyword. The type specifies what is being compared. The comparison to use is specified by comp and only some comparisons are valid for a given rule type. See below for more.
One detail to keep track of is that a device like fwfpm will report its position while still moving. So next we create a rule to check if fwfpm is moving or not. We can do this with the fwfpm.fsm_state property and its state element, which will be READY if fwfpm is stopped in its commanded position:
The above rule will be true if and only if fwfpm.fsm_state.state==READY.
Now we combine these into a rule to test if fwfpm is stopped in the fpm position:
The above rule performs the logical AND comparison between two rules, and so is true if and only if both are true.
One more rule we need is a test if the two devices fwfpm and stagesci1 are not in the corresponding position.
The above rule will evaluate to true if fwfpm.filterName.fpm and stagesci1.presetName.fpm are not in the same position by comparing the states of their corresponding preset/filter selection switches.
Finally, we combine all of the above rules into a rule to raise a caution if fwfpm is in position fpm, stopped, and stagesci is not in the fpm position.
Now the user can be notified to take caution whenever this out-of-focus state occurs. The value of the message keyword is used for notifications. When a published rule transitions from On to Off, stateRuleEngine also sends a one-time informational clear notification in the form INFO: Cleared: <message>, falling back to the rule name when message is not set.
For combinations that depend on several active switch-vector elements, use multiSwitchCombo to derive a target preset name from the currently active element in each source switch property:
This rule reads the active element name from each source switch property, formats those names into one string, and compares that derived string to the active element name in targetProperty. The default comparison for multiSwitchCombo is Neq, so the rule is true when the derived combo and target preset do not match. A source or target switch property with no active element contributes an empty string. If a source or target switch property has multiple active elements, multiSwitchCombo also uses an empty string, but logs one software_error when the property enters that multi-On state.
The rules are configured using the usual MagAO-X TOML .conf files. A rule is named by its TOML section heading, e.g. [rule-name], and then specified by the keywords. Which keywords are valid depends on the ruleType. The following table lists the keywords.
| keyword | Required | Default | ruleTypes | Purpose |
|---|---|---|---|---|
| ruleType | Y | the type of rule | ||
| priority | N | none | all | the reporting priority |
| message | N | all | descriptive message used for user feedback | |
| comp | N | rule-dependent | all | the comparison to use |
| property | Y | numVal, txtVal, swVal | the INDI property | |
| element | Y | numVal, txtVal, swVal | the element within property | |
| property1 | Y | elCompNum, elCompTxt, elCompSw | the first INDI property | |
| element1 | Y | elCompNum, elCompTxt, elCompSw | the element within property1 | |
| property2 | Y | elCompNum, elCompTxt, elCompSw | the second INDI property | |
| element2 | Y | elCompNum, elCompTxt, elCompSw | the element within property2 | |
| numSwitches | Y | multiSwitchCombo | the number of source switch properties to combine | |
| property1...propertyN | Y | multiSwitchCombo | the source switch properties to combine, in format order | |
| format | Y | multiSwitchCombo | literal {} placeholder format used to combine active source-element names | |
| targetProperty | Y | multiSwitchCombo | the target switch property whose active element name is compared | |
| rule1 | Y | ruleComp | the first rule | |
| rule2 | Y | ruleComp | the second rule | |
| tol | N | 1e-6 | numVal, elCompNum | the tolerance for equality of numbers |
Note that required keywords are only required in their respective ruleTypes.
Additional information about keywords is provided below.
The ruleType keyword specifies the type of rule, and the comp keyword specifies the logical comparison to use. They go together as described in the following table.
ruleType | Description | Valid comparisons for comp | Notes |
|---|---|---|---|
| numVal | compare the value of a number element to a numeric value | Eq, Neq, Lt, LtEq, Gt, GtEq | equality is tested with a tolerance |
| txtVal | compare the value of a text element to a text value | Eq, Neq | |
| swVal | compare the state of a switch to either On or Off | Eq, Neq | |
| timeDiff | compare the difference between now and a time | Eq, Neq, Lt, LtEq, Gt, GtEq | equality is tested with a tolerance |
| elCompNum | compare the value of two number elements to each other | Eq, Neq, Lt, LtEq, Gt, GtEq | equality is tested with a tolerance |
| elCompTxt | compare the value of two text elements to each other | Eq, Neq | |
| elCompSw | compare the value of two switch elements to each other | Eq, Neq | |
| multiSwitchCombo | compare a formatted combination of active switch-element names to the active element name of a target switch property | Eq, Neq | defaults comp to Neq; supports literal {} placeholders only |
| ruleComp | compare the value of two rules to each other | Eq/Xnor, Neq/Xor, And, Nand, Or, Nor, Imply, Nimply | |
Default comp is Eq for all rule types except ruleComp and multiSwitchCombo, which default to And and Neq respectively.
(Note: Imply and Nimply are not commutative; the rule order matters)
|priority | Description | Notes | |:------—:|-------------------------------------------------------------—|--------------------------—| | none | not published | info | | | caution | | | warning | | | alert | |
For numerical comparisons, equality is tested with a tolerance, specified by the keyword tol in the config file. This accounts for floating point nonsense and the binary-text-binary conversions inherent in the INDI protocol. The default for tol is 1e-6. If you set it to 0 you will get strict equality checking.
1.9.8