1# LED Support for OpenBMC
2
3This document describes how to add LED support for your machine based upon the
4OpenBMC [LED Architecture][LED D-Bus README] document. LED group management is
5done automatically for machines that support the use of the MRW and is beyond
6the scope of this document.
7
8## D-Bus
9
10```
11Service     xyx.openbmc_project.LED.GroupManager
12Path        /xyz/openbmc_project/led/groups/<label>
13Interfaces  xyz.openbmc_project.Led.Group
14
15Signals: none
16Attribute: Asserted (boolean)
17```
18
19## REST
20
21```
22PUT /xyz/openbmc_project/led/groups/<group>/attr/Asserted
23```
24
25The LED group state can be changed by setting the Asserted value to boolean 0 or 1.
26In the following example, the lamp_test group is being asserted...
27```
28 curl -b cjar -k -X PUT -H "Content-Type: application/json" -d '{"data":  1}' \
29  https://${bmc}/xyz/openbmc_project/led/groups/lamp_test/attr/Asserted
30```
31
32## REDFISH
33
34### Resource identify Operation
35Starting with Redfish v2020.3, Redfish resources have **LocationIndicatorActive**
36property, which is used to identify a particular resource. This is for LED
37Identify operation only.
38
39All applicable Inventory D-Bus objects would have a forward association
40mapping to LED Group D-Bus object, namely:
41```
42 - identify_led_group
43```
44All applicable LED Group D-Bus objects would have an association mapping to
45inventory D-Bus object, namely:
46```
47 - identify_inventory_object
48```
49
50When a `LocationIndicatorActive` GET operation is performed on the resource,
51bmcweb does below operations:
52- Look for an association `identify_led_group` on the Inventory D-Bus object
53- If found, read the `asserted` property from the D-Bus object that is pointed
54  to by `identify_led_group`
55
56When a `LocationIndicatorActive` PATCH operation is performed on the resource,
57bmcweb does below operations:
58- Look for an association `identify_led_group` on the Inventory D-Bus object
59- If found, set the `asserted` property on the D-Bus object that is pointed
60  to by `identify_led_group`
61
62
63## Development Details
64There are two significant layers for LED operations.  The physical and the
65logical.  The LED Group Manager communicates with the physical LED Manager to
66drive the physical LEDs.  The logical groups are defined in the machine's
67led.yaml file.  LED Group manager consumes this and creates D-Bus/REST
68interfaces for the individual LEDs that are part of the group.
69
70### Defining the physical LED
71
72Physical LED wiring is defined in the `leds` section of the machine's
73[device tree][Kernel ARM DTS]. See the [Palmetto DTS][Palmetto DTS LED]
74as an example.
75
76_Add a fault LED to the device tree with a corresponding gpio pin..._
77```
78  leds {
79    compatible = "gpio-leds";
80
81    fault {
82      gpios = <&gpio ASPEED_GPIO(N, 2) GPIO_ACTIVE_LOW>;
83    };
84  }
85```
86
87_The kernel will then create..._
88
89```
90 ls -l /sys/class/leds/fault/
91total 0
92-rw-r--r--    1 root     root          4096 Jun 21 20:04 brightness
93lrwxrwxrwx    1 root     root             0 Jun 21 20:29 device -> ../../../leds
94-r--r--r--    1 root     root          4096 Jun 21 20:29 max_brightness
95drwxr-xr-x    2 root     root             0 Jun 21 20:29 power
96lrwxrwxrwx    1 root     root             0 Jun 21 20:04 subsystem -> ../../../../../class/leds
97-rw-r--r--    1 root     root          4096 Jun 21 20:04 trigger
98-rw-r--r--    1 root     root          4096 Jun 21 20:04 uevent
99```
100
101### Defining Groups
102An LED Group can contain zero or more LEDs and is defined in the machines
103[led.yaml][LED YAML]. The default one will likely need to be tailored to your
104machines layout. Customized yaml files are placed into the machines specific
105Yocto location. As an example:
106
107```
108meta-ibm/meta-palmetto/recipes-phosphor/leds/palmetto-led-manager-config/led.yaml
109```
110
111The parent properties in the yaml file will be created below `/xyz/openbmc_project/led/groups/`.
112The children properties need to map to an LED name in `/sys/class/leds`.
113
114In the example, below two URIs would be created:
115`/xyz/openbmc_project/led/groups/enclosure_fault` and
116`/xyz/openbmc_project/led/groups/lamp_test`.  Both act on the same physical
117LED `fault` but do so differently.  The lamp_test would also drive a blink
118signal to the physical `power` LED if one was created.
119
120
121```
122EnclosureFault:
123    fault:
124        Action: 'On'
125        DutyOn: 50
126        Period: 0
127lamp_test:
128    fault:
129        Action: 'Blink'
130        DutyOn: 20
131        Period: 100
132    power:
133        Action: 'Blink'
134        DutyOn: 20
135        Period: 100
136
137```
138
139### Required Groups
140OpenBMC Architecture requires specific LED Groups to be created and are
141documented in the [D-Bus interface][LED D-Bus README].
142
143
144## Yocto packaging
1451.  Create a tailored LED manager file
146
147    E.g. `meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config-native.bb`
148    ```
149    SUMMARY = "Phosphor LED Group Management for Romulus"
150    PR = "r1"
151
152    inherit native
153    inherit obmc-phosphor-utils
154    inherit obmc-phosphor-license
155
156    PROVIDES += "virtual/phosphor-led-manager-config-native"
157
158    SRC_URI += "file://led.yaml"
159    S = "${WORKDIR}"
160
161    # Overwrites the default led.yaml
162    do_install() {
163        SRC=${S}
164        DEST=${D}${datadir}/phosphor-led-manager
165        install -D ${SRC}/led.yaml ${DEST}/led.yaml
166    }
167    ```
1682. Change your machine's preferred provider for the led-manager in the conf file
169
170    E.g. `meta-ibm/meta-romulus/conf/machine/romulus.conf`
171
172    ```PREFERRED_PROVIDER_virtual/phosphor-led-manager-config-native = "romulus-led-manager-config-native"```
173
174
175[LED D-Bus README]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/README.md
176[LED YAML]: https://github.com/openbmc/phosphor-led-manager/blob/master/led.yaml
177[Kernel ARM DTS]: https://github.com/openbmc/linux/tree/dev-4.19/arch/arm/boot/dts
178[Palmetto DTS LED]: https://github.com/openbmc/linux/blob/dev-4.19/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dts#L45
179