docs/architecture/LED-architecture.md

1 # LED Support for OpenBMC
3 This document describes how to add LED support for your machine based upon the
4 OpenBMC [LED Architecture][led d-bus readme] document. LED group management is
8 ## D-Bus
11 Service     xyx.openbmc_project.LED.GroupManager
12 Path        /xyz/openbmc_project/led/groups/<label>
13 Interfaces  xyz.openbmc_project.Led.Group
22 PUT /xyz/openbmc_project/led/groups/<group>/attr/Asserted
25 The LED group state can be changed by setting the Asserted value to boolean 0
26 or 1. In the following example, the lamp_test group is being asserted...
29  curl -b cjar -k -X PUT -H "Content-Type: application/json" -d '{"data":  1}' \
30   https://${bmc}/xyz/openbmc_project/led/groups/lamp_test/attr/Asserted
39 resource. This is for LED Identify operation only.
41 All applicable Inventory D-Bus objects would have a forward association mapping
42 to LED Group D-Bus object, namely:
45  - identify_led_group
48 All applicable LED Group D-Bus objects would have an association mapping to
49 inventory D-Bus object, namely:
52  - identify_inventory_object
58 - Look for an association `identify_led_group` on the Inventory D-Bus object
59 - If found, read the `asserted` property from the D-Bus object that is pointed
65 - Look for an association `identify_led_group` on the Inventory D-Bus object
66 - If found, set the `asserted` property on the D-Bus object that is pointed to
72 used. All applicable Inventory D-Bus objects would have a forward association
73 mapping to LED Group D-Bus object, namely;
76  - fault_led_group
79 All applicable LED Group D-Bus objects would have an association mapping to
80 inventory D-Bus object, namely:
83  - fault_inventory_object
88 on the Inventory D-Bus object.
90 When LED manager gets PropertyChanged signal, it does the following:
92 - Look for an association `fault_led_group` on the Inventory D-Bus object
93 - Turn on/off the fault LED group depending on the value of `Functional` `false`
94   would mean turn ON the LED group `true` would mean turn OFF the LED group
96 - bmcweb already has a design to look for `Functional` property and set the
101 There are two significant layers for LED operations. The physical and the
102 logical. The LED Group Manager communicates with the physical LED Manager to
104 led.yaml file. LED Group manager consumes this and creates D-Bus/REST interfaces
107 ### Defining the physical LED
109 Physical LED wiring is defined in the `leds` section of the machine's [device
110 tree][kernel arm dts]. See the [Palmetto DTS][palmetto dts led] as an example.
112 _Add a fault LED to the device tree with a corresponding gpio pin..._
116     compatible = "gpio-leds";
127  ls -l /sys/class/leds/fault/
129 -rw-r--r--    1 root     root          4096 Jun 21 20:04 brightness
130 lrwxrwxrwx    1 root     root             0 Jun 21 20:29 device -> ../../../leds
131 -r--r--r--    1 root     root          4096 Jun 21 20:29 max_brightness
132 drwxr-xr-x    2 root     root             0 Jun 21 20:29 power
133 lrwxrwxrwx    1 root     root             0 Jun 21 20:04 subsystem -> ../../../../../class/leds
134 -rw-r--r--    1 root     root          4096 Jun 21 20:04 trigger
135 -rw-r--r--    1 root     root          4096 Jun 21 20:04 uevent
140 An LED Group can contain zero or more LEDs and is defined in the machines
141 [led.yaml][led yaml]. The default one will likely need to be tailored to your
146 meta-ibm/meta-palmetto/recipes-phosphor/leds/palmetto-led-manager-config/led.yaml
150 `/xyz/openbmc_project/led/groups/`. The children properties need to map to an
151 LED name in `/sys/class/leds`.
154 `/xyz/openbmc_project/led/groups/enclosure_fault` and
155 `/xyz/openbmc_project/led/groups/lamp_test`. Both act on the same physical LED
157 the physical `power` LED if one was created.
179 OpenBMC Architecture requires specific LED Groups to be created and are
180 documented in the [D-Bus interface][led d-bus readme].
184 1.  Create a tailored LED manager file
187     `meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config-native.bb`
190     SUMMARY = "Phosphor LED Group Management for Romulus"
194     inherit obmc-phosphor-utils
195     inherit obmc-phosphor-license
197     PROVIDES += "virtual/phosphor-led-manager-config-native"
199     SRC_URI += "file://led.yaml"
202     # Overwrites the default led.yaml
205         DEST=${D}${datadir}/phosphor-led-manager
206         install -D ${SRC}/led.yaml ${DEST}/led.yaml
210 2.  Change your machine's preferred provider for the led-manager in the conf
213     E.g. `meta-ibm/meta-romulus/conf/machine/romulus.conf`
215 …`PREFERRED_PROVIDER_virtual/phosphor-led-manager-config-native = "romulus-led-manager-config-nativ…
217 [led d-bus readme]:
218 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/READM…
219 [led yaml]: https://github.com/openbmc/phosphor-led-manager/blob/master/led.yaml
221   https://github.com/openbmc/linux/tree/dev-4.19/arch/arm/boot/dts
222 [palmetto dts led]:
223   https://github.com/openbmc/linux/blob/dev-4.19/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dts#L45