control:docs: Create events.md
This describes the events.json file. Only an introduction and example
is added with this commit. Further details will be added in future
commits.
Signed-off-by: Matt Spinler <spinler@us.ibm.com>
Change-Id: If50579d6b26afb979933d4f085cdb21ab14235b2
diff --git a/docs/control/events.md b/docs/control/events.md
new file mode 100644
index 0000000..572926e
--- /dev/null
+++ b/docs/control/events.md
@@ -0,0 +1,67 @@
+# events.json
+
+This file defines the events that dictate how fan control operates. Each event
+can contain groups, triggers, and actions.
+
+Actions are where fan targets are calculated and set, among other things.
+Triggers specify when an action should run. Groups specify which D-Bus objects
+the triggers and actions should operate on.
+
+Some actions have modifiers, which help calculate a value.
+
+- [Groups](#groups)
+- [Triggers](#triggers)
+- [Actions](#actions)
+- [Modifiers](#modifiers)
+
+## Example
+
+```
+[
+ {
+ "name": "fan(s) missing",
+ "groups": [
+ {
+ "name": "fan inventory",
+ "interface": "xyz.openbmc_project.Inventory.Item",
+ "property": { "name": "Present" }
+ }
+ ],
+ "triggers": [
+ {
+ "class": "init",
+ "method": "get_properties"
+ },
+ {
+ "class": "signal",
+ "signal": "properties_changed"
+ }
+ ],
+ "actions": [
+ {
+ "name": "count_state_before_target",
+ "count": 1,
+ "state": false,
+ "target": 15000
+ }
+ ]
+ }
+]
+```
+
+The above event is an example of a method to set the fan target to 15000 when
+one or more fans is missing. The basic behavior with this config is:
+
+The trigger `init.get_properties` will, on fan control startup, read the
+Present property on the `xyz.openbmc_project.Inventory.Item` interface from
+every D-Bus object in the 'fan inventory' group, update those values in the
+object cache, and then call the `count_state_before_target` action.
+
+The trigger `signal.properties_changed` will watch for changes on the Present
+property on each D-Bus object in the group, update the new value in the object
+cache, and call the `count_state_before_target` action when the value changes.
+
+The `count_state_before_target` action will look at the object cache value of
+the Present property on each member of the group and set the fan target hold to
+15000 when one or more of them is false. Otherwise, it will clear its fan
+target hold.