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```
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```
58This says that the group `bmc_booted` consists of 2 physical LEDs in it.
59When this group is acted on, led_1 will turn solid [ON], while led_2
60would be blinking at 50% duty cycle.
61
62## Dbus interfaces for LED groups.
63
64Refer: [specification](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/Group.interface.yaml)
65
66There is only one property called **asserted** defined on groups and when set to
67boolean **true**, the actions listed for the LEDs in that group will get into
68effect as described above.
69When the property is set to **false**, the actions are un-done.
70
71* Henceforth, the term **asserted** would mean writing boolean **true**
72  onto `assert` property of the group. Term **de-assert** would mean
73  writing **false** to `assert` property.
74
75## Group Dbus information
76
77**Path: "/xyz/openbmc_project/led/groups/<name>"**
78**Interface: "xyz.openbmc_Project.Led.Group"**
79
80Using the yaml definition above, a user can just set the `asserted` property to
81boolean `true` on '/xyz/openbmc_project/led/groups/enclosure_identify' and that
82would result in blinking the front and rear Identify LEDs of the enclosure.
83
84## Mandatory groups
85
86It is mandatory that all implementations provide definitions of atleast 2 groups
87namely; **bmc_booted** and **power_on**. Those would be asserted post reaching
88BMCReady and PowerOn respecively. It is fine to have no LEDs in those groups but
89the group as such is deemed required.
90
91Example: The Group yaml may just be;
92```
93bmc_booted:
94power_on:
95```
96
97For the IPMI command "chassis identify" to function, **enclosure_identify** must
98also be implemented.
99
100## Understanding Physical LEDs
101
102It is always **recommended** that external users use **only** the LED groups.
103Describing the Physical LED here just for documenting it and strictly NOT to
104be used outside of the firmware code.
105
106## Dbus interfaces for physical LEDs.
107
108Refer: [specification](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/Physical.interface.yaml)
109
110## Dbus information
111
112**Path: "/xyz/openbmc_project/led/physical/<name>"**
113**Interface: "xyz.openbmc_Project.Led.Physical"**
114
115Using **/xyz/openbmc_project/led/groups/enclosure_identify** as example;
116setting the `asserted` property to `true` would result in these actions in
117*id_front* and *id_rear* physical LEDs.
118
1191) Property *DutyOn* is set to `50` in;
120  `/xyz/openbmc/project/led/physical/id_front` and
121  `/xyz/openbmc/project/led/physical/id_rear`
122
1232) Property *State* is set to `xyz.openbmc_project.Led.Physical.Action.On` in
124   `/xyz/openbmc/project/led/physical/id_front` and
125   `/xyz/openbmc/project/led/physical/id_rear`
126
127Which means, if some test wants to verify if the action on Group really resulted
128in acting on physical LED, those are the properties to be read from physical
129service.
130
131#                                         END of Document
132