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
7to control 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
12hard when 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
18to be solid [ON] while some LEDs to be Blinking etc.
19
20As described above, it is more of a system specific policy on what set
21of LEDs to be acted on in different usecases. Taking all that complexity into
22the code makes it impossible to extend across implementations and hence the need
23of a manager 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:
26Consider a requirement of blinking system Enclosure LED indicating
27an internal problem:
28
29If the DIMM has some issues then the system admin needs a way of identifying
30that system before acting on it. In one case, the LED group may consist of
31DIMM LED + Enclosure Fault LED. However, if the DIMM is attached to a Raiser
32card, then the LED group may consist of DIMM LED + Raise card LED + Enclosure
33Fault LED. Defining this path will make it easier to locate the box and the
34exact part that needs servicing.
35
36Definition of LED groups could be static or generated from MRW and must be in
37YAML format. A group definition looks like this:
38
39```yaml
40bmc_booted:
41  led_1:
42    Action: On
43    Frequency: 1000
44  led_2:
45    Action: Blink
46    Frequency: 1000
47    DutyOn: 50
48
49enclosure_identify:
50  id_front:
51    Action: Blink
52    Frequency: 1000
53    DutyOn: 50
54  id_rear:
55    Action: Blink
56    Frequency: 1000
57    DutyOn: 50
58```
59
60This says that the group `bmc_booted` consists of 2 physical LEDs in it.
61When this group is acted on, led_1 will turn solid [ON], while led_2
62would be blinking at 50% duty cycle.
63
64## Dbus interfaces for LED groups
65
66Refer to the [specification][group_specification].
67
68[group_specification]: 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.
73When the property is set to **false**, the actions are un-done.
74
75- Henceforth, the term **asserted** would mean writing boolean **true**
76  onto `assert` property of the group. Term **de-assert** would mean
77  writing **false** to `assert` property.
78
79## Group Dbus information
80
81**Path: `/xyz/openbmc_project/led/groups/<name>`**
82**Interface: `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
109be used outside of the firmware code.
110
111## Dbus interfaces for physical LEDs
112
113Refer to the [specification][phys_specification].
114
115[phys_specification]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/Physical.interface.yaml
116
117## Dbus information
118
119**Path: `/xyz/openbmc_project/led/physical/<name>`**
120**Interface: `xyz.openbmc_Project.Led.Physical`**
121
122Using **/xyz/openbmc_project/led/groups/enclosure_identify** as example;
123setting the `asserted` property to `true` would result in these actions in
124`id_front` and `id_rear` physical LEDs.
125
1261. Property `DutyOn` is set to `50` in;
127   `/xyz/openbmc/project/led/physical/id_front` and
128   `/xyz/openbmc/project/led/physical/id_rear`
129
1302. Property `State` is set to `xyz.openbmc_project.Led.Physical.Action.On` in
131   `/xyz/openbmc/project/led/physical/id_front` and
132   `/xyz/openbmc/project/led/physical/id_rear`
133
134Which means, if some test wants to verify if the action on Group really resulted
135in acting on physical LED, those are the properties to be read from physical
136service.
137