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
33## Development Details
34There are two significant layers for LED operations.  The physical and the
35logical.  The LED Group Manager communicates with the physical LED Manager to
36drive the physical LEDs.  The logical groups are defined in the machine's
37led.yaml file.  LED Group manager consumes this and creates D-Bus/REST
38interfaces for the individual LEDs that are part of the group.
39
40### Defining the physical LED
41
42Physical LED wiring is defined in the `leds` section of the machine's
43[device tree][Kernel ARM DTS]. See the [Palmetto DTS][Palmetto DTS LED]
44as an example.
45
46_Add a fault LED to the device tree with a corresponding gpio pin..._
47```
48  leds {
49    compatible = "gpio-leds";
50
51    fault {
52      gpios = <&gpio ASPEED_GPIO(N, 2) GPIO_ACTIVE_LOW>;
53    };
54  }
55```
56
57_The kernel will then create..._
58
59```
60 ls -l /sys/class/leds/fault/
61total 0
62-rw-r--r--    1 root     root          4096 Jun 21 20:04 brightness
63lrwxrwxrwx    1 root     root             0 Jun 21 20:29 device -> ../../../leds
64-r--r--r--    1 root     root          4096 Jun 21 20:29 max_brightness
65drwxr-xr-x    2 root     root             0 Jun 21 20:29 power
66lrwxrwxrwx    1 root     root             0 Jun 21 20:04 subsystem -> ../../../../../class/leds
67-rw-r--r--    1 root     root          4096 Jun 21 20:04 trigger
68-rw-r--r--    1 root     root          4096 Jun 21 20:04 uevent
69```
70
71### Defining Groups
72An LED Group can contain zero or more LEDs and is defined in the machines
73[led.yaml][LED YAML]. The default one will likely need to be tailored to your
74machines layout. Customized yaml files are placed into the machines specific
75Yocto location. As an example:
76
77```
78meta-ibm/meta-palmetto/recipes-phosphor/leds/palmetto-led-manager-config/led.yaml
79```
80
81The parent properties in the yaml file will be created below `/xyz/openbmc_project/led/groups/`.
82The children properties need to map to an LED name in `/sys/class/leds`.
83
84In the example, below two URIs would be created:
85`/xyz/openbmc_project/led/groups/enclosure_fault` and
86`/xyz/openbmc_project/led/groups/lamp_test`.  Both act on the same physical
87LED `fault` but do so differently.  The lamp_test would also drive a blink
88signal to the physical `power` LED if one was created.
89
90
91```
92EnclosureFault:
93    fault:
94        Action: 'On'
95        DutyOn: 50
96        Period: 0
97lamp_test:
98    fault:
99        Action: 'Blink'
100        DutyOn: 20
101        Period: 100
102    power:
103        Action: 'Blink'
104        DutyOn: 20
105        Period: 100
106
107```
108
109### Required Groups
110OpenBMC Architecture requires specific LED Groups to be created and are
111documented in the [D-Bus interface][LED D-Bus README].
112
113
114## Yocto packaging
1151.  Create a tailored LED manager file
116
117    E.g. `meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config-native.bb`
118    ```
119    SUMMARY = "Phosphor LED Group Management for Romulus"
120    PR = "r1"
121
122    inherit native
123    inherit obmc-phosphor-utils
124    inherit obmc-phosphor-license
125
126    PROVIDES += "virtual/phosphor-led-manager-config-native"
127
128    SRC_URI += "file://led.yaml"
129    S = "${WORKDIR}"
130
131    # Overwrites the default led.yaml
132    do_install() {
133        SRC=${S}
134        DEST=${D}${datadir}/phosphor-led-manager
135        install -D ${SRC}/led.yaml ${DEST}/led.yaml
136    }
137    ```
1382. Change your machine's preferred provider for the led-manager in the conf file
139
140    E.g. `meta-ibm/meta-romulus/conf/machine/romulus.conf`
141
142    ```PREFERRED_PROVIDER_virtual/phosphor-led-manager-config-native = "romulus-led-manager-config-native"```
143
144
145[LED D-Bus README]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/README.md
146[LED YAML]: https://github.com/openbmc/phosphor-led-manager/blob/master/led.yaml
147[Kernel ARM DTS]: https://github.com/openbmc/linux/tree/dev-4.19/arch/arm/boot/dts
148[Palmetto DTS LED]: https://github.com/openbmc/linux/blob/dev-4.19/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dts#L45
149