1# Managing LED groups and physical LEDs through BMC
2
3## Overview
4
5LEDs that are present in the system can be managed by:
6`BMC / Hardware controller / Operating system`. This document describes how to
7control the LEDs that are managed by BMC.
8
9## Understanding LED groups
10
11While it is entirely possible to act directly on a physical LED, it makes hard
12when more than one LED is to be acted on for a particular usecase.
13
14For example: Certain systems may have a requirement to **Blink** one particular
15LED upon reaching some state. However, some other systems may have a requirement
16to **Blink** set of LEDs in different frequencies. Few more systems may have a
17requirement to act on set of LEDs with different actions. Meaning, some LEDs to
18be solid [ON] while some LEDs to be Blinking etc.
19
20As described above, it is more of a system specific policy on what set of LEDs
21to be acted on in different usecases. Taking all that complexity into the code
22makes it impossible to extend across implementations and hence the need of a
23manager that works on the set of LEDs and policies and that is the Group.
24
25To make concept of Group more evident, here is another example: Consider a
26requirement of blinking system Enclosure LED indicating an internal problem:
27
28If the DIMM has some issues then the system admin needs a way of identifying
29that system before acting on it. In one case, the LED group may consist of DIMM
30LED + Enclosure Fault LED. However, if the DIMM is attached to a Raiser card,
31then the LED group may consist of DIMM LED + Raise card LED + Enclosure Fault
32LED. Defining this path will make it easier to locate the box and the exact part
33that needs servicing.
34
35Definition of LED groups could be static or generated from MRW and must be in
36YAML format. A group definition looks like this:
37
38```yaml
39bmc_booted:
40  led_1:
41    Action: On
42    Frequency: 1000
43  led_2:
44    Action: Blink
45    Frequency: 1000
46    DutyOn: 50
47
48enclosure_identify:
49  id_front:
50    Action: Blink
51    Frequency: 1000
52    DutyOn: 50
53  id_rear:
54    Action: Blink
55    Frequency: 1000
56    DutyOn: 50
57```
58
59This says that the group `bmc_booted` consists of 2 physical LEDs in it. When
60this group is acted on, led_1 will turn solid [ON], while led_2 would be
61blinking at 50% duty cycle.
62
63## Dbus interfaces for LED groups
64
65Refer to the [specification][group_specification].
66
67[group_specification]:
68  https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/Group.interface.yaml
69
70There is only one property called **asserted** defined on groups and when set to
71boolean **true**, the actions listed for the LEDs in that group will get into
72effect as described above. When the property is set to **false**, the actions
73are un-done.
74
75- Henceforth, the term **asserted** would mean writing boolean **true** onto
76  `assert` property of the group. Term **de-assert** would mean writing
77  **false** to `assert` property.
78
79## Group Dbus information
80
81**Path: `/xyz/openbmc_project/led/groups/<name>`** **Interface:
82`xyz.openbmc_Project.Led.Group`**
83
84Using the yaml definition above, a user can just set the `asserted` property to
85boolean `true` on `/xyz/openbmc_project/led/groups/enclosure_identify` and that
86would result in blinking the front and rear Identify LEDs of the enclosure.
87
88## Mandatory groups
89
90It is mandatory that all implementations provide definitions of atleast 2 groups
91namely; **bmc_booted** and **power_on**. Those would be asserted post reaching
92BMCReady and PowerOn respecively. It is fine to have no LEDs in those groups but
93the group as such is deemed required.
94
95Example: The Group yaml may just be;
96
97```yaml
98bmc_booted:
99power_on:
100```
101
102For the IPMI command "chassis identify" to function, **enclosure_identify** must
103also be implemented.
104
105## Understanding Physical LEDs
106
107It is always **recommended** that external users use **only** the LED groups.
108Describing the Physical LED here just for documenting it and strictly NOT to be
109used outside of the firmware code.
110
111## Dbus interfaces for physical LEDs
112
113Refer to the [specification][phys_specification].
114
115[phys_specification]:
116  https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/Physical.interface.yaml
117
118## Dbus information
119
120**Path: `/xyz/openbmc_project/led/physical/<name>`** **Interface:
121`xyz.openbmc_Project.Led.Physical`**
122
123Using **/xyz/openbmc_project/led/groups/enclosure_identify** as example; setting
124the `asserted` property to `true` would result in these actions in `id_front`
125and `id_rear` physical LEDs.
126
1271. Property `DutyOn` is set to `50` in;
128   `/xyz/openbmc/project/led/physical/id_front` and
129   `/xyz/openbmc/project/led/physical/id_rear`
130
1312. Property `State` is set to `xyz.openbmc_project.Led.Physical.Action.On` in
132   `/xyz/openbmc/project/led/physical/id_front` and
133   `/xyz/openbmc/project/led/physical/id_rear`
134
135Which means, if some test wants to verify if the action on Group really resulted
136in acting on physical LED, those are the properties to be read from physical
137service.
138