1# events.json
2
3This file defines the events that dictate how fan control operates.  Each event
4can contain groups, triggers, and actions.
5
6Actions are where fan targets are calculated and set, among other things.
7Triggers specify when an action should run. Groups specify which D-Bus objects
8the triggers and actions should operate on.
9
10Some actions have modifiers, which help calculate a value.
11
12- [Groups](#groups)
13- [Triggers](#triggers)
14- [Actions](#actions)
15- [Modifiers](#modifiers)
16
17## Example
18
19```
20[
21   {
22     "name": "fan(s) missing",
23     "groups": [
24       {
25         "name": "fan inventory",
26         "interface": "xyz.openbmc_project.Inventory.Item",
27         "property": { "name": "Present" }
28       }
29     ],
30     "triggers": [
31       {
32         "class": "init",
33         "method": "get_properties"
34       },
35       {
36         "class": "signal",
37         "signal": "properties_changed"
38       }
39     ],
40     "actions": [
41       {
42         "name": "count_state_before_target",
43         "count": 1,
44         "state": false,
45         "target": 15000
46       }
47     ]
48   }
49]
50```
51
52The above event is an example of a method to set the fan target to 15000 when
53one or more fans is missing. The basic behavior with this config is:
54
55The trigger `init.get_properties` will, on fan control startup, read the
56Present property on the `xyz.openbmc_project.Inventory.Item` interface from
57every D-Bus object in the 'fan inventory' group, update those values in the
58object cache, and then call the `count_state_before_target` action.
59
60The trigger `signal.properties_changed` will watch for changes on the Present
61property on each D-Bus object in the group, update the new value in the object
62cache, and call the `count_state_before_target` action when the value changes.
63
64The `count_state_before_target` action will look at the object cache value of
65the Present property on each member of the group and set the fan target hold to
6615000 when one or more of them is false.  Otherwise, it will clear its fan
67target hold.
68
69## Groups
70
71```
72"groups": [
73    {
74        "name": "<name>",
75        "interface": "<interface>",
76        "property": { "name": "<name>" }
77    }
78    ...
79]
80```
81
82### name
83The name of a group that must be also be defined in
84[groups.json](groups.md).
85
86### interface
87The actions and triggers defined with this group will look at this D-Bus
88interface on the members of this group.
89
90### property: name
91The actions and triggers defined with this group will look at this D-Bus
92property on the members of this group.
93
94## Triggers
95
96There are several classes of triggers, and the JSON configuration is different
97for each.
98
99### init
100Init triggers run when fan control events are enabled on fan control startup.
101After invoking the configured method, any actions configured for this trigger
102will run.
103
104```
105{
106    "class": "init",
107    "method": "<method>"
108}
109```
110
111#### methods
112
1131. `get_properties` - Read the property configured for the group from every
114   member of the group, and store it in fan control's object cache.
115
1162. `name_has_owner` - Populates the service owned state from D-Bus for each
117   group member in fan control's D-Bus service cache map.
118
119### signal
120Signal triggers subscribe to certain D-Bus signals for each member of its
121configured group.  After handling the signal, any configured actions are run.
122
123```
124{
125    "class": "signal",
126    "signal": "<signal>"
127}
128```
129
130#### signal types
1311. `properties_changed` - Subscribes to the PropertiesChanged signal for the
132   D-Bus interface and property specified in the group definition for each
133   group member.  When the signal occurs, the new property value will be added
134   to or updated in the object cache.
135
1362. `interfaces_added` - Subscribes to the InterfacesAdded signal for the D-Bus
137   interface specified in the group definition for each group member.  When the
138   signal occurs, the interface and its properties will be added to the object
139   cache.
140
1413. `interfaces_removed` - Subscribes to the InterfacesRemoved signal for the
142   D-Bus interface specified in the group definition for each group member.
143   When the signal occurs, the interface and properties will be removed from
144   the object cache.
145
1464. `name_owner_changed` - Subscribes to the NameOwnerChanged signal for the
147   services that host the D-bus interface specified in the group definition for
148   each group member.  When the signal occurs, the service owned state will be
149   updated in the service cache map.
150
1515. `member` - Subscribes to the signal listed on each group member.  No caches
152   are updated when the signal occurs.
153
154### timer
155Timer triggers run actions after the configured type of timer expires.
156
157```
158{
159    "class": "timer",
160    "type": "<type>",
161    "interval": "<interval>",
162    "preload_groups": "<true/false>"
163}
164```
165
166#### type
1671. `oneshot` - Starts a timer that runs once.
168
1692. `repeating` - Starts a repeating timer.
170
171#### interval
172The timer length in microseconds
173
174#### preload_groups
175Optional, if set to true, will update the D-Bus properties from the configured
176groups in the object cache after the timer expires but before any actions run.
177
178### parameter
179Parameter triggers run actions after a parameter changes.
180
181```
182{
183    "class": "parameter",
184    "parameter": "<parameter>"
185}
186```
187#### parameter
188The parameter value to watch.
189
190### poweron
191PowerOn triggers run when the power turns on.  Functionally, they behave like
192an init trigger.
193
194```
195{
196    "class": "poweron",
197    "method": "<method>"
198}
199```
200
201#### method
202The methods are the same as with the init trigger.
203
204### poweroff
205
206PowerOff triggers run when the power turns off.  Functionally, they behave like
207an init trigger.
208
209```
210{
211    "class": "poweroff",
212    "method": "<method>"
213}
214```
215
216#### method
217The methods are the same as with the init trigger.
218