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### Representing resource faults 63For representing the fault status of a resource, Redfish `Health` property is 64used. 65All applicable Inventory D-Bus objects would have a forward association mapping 66to LED Group D-Bus object, namely; 67``` 68 - fault_led_group 69``` 70All applicable LED Group D-Bus objects would have an association mapping to 71inventory D-Bus object, namely: 72``` 73 - fault_inventory_object 74``` 75 76When a component fault is detected, the responsible code sets the `Functional` 77property of `xyz.openbmc_project.State.Decorator.OperationalStatus` to `false` 78on the Inventory D-Bus object. 79 80When LED manager gets PropertyChanged signal, it does the following: 81- Look for an association `fault_led_group` on the Inventory D-Bus object 82- Turn on/off the fault LED group depending on the value of `Functional` 83 `false` would mean turn ON the LED group 84 `true` would mean turn OFF the LED group 85 86- bmcweb already has a design to look for `Functional` property and set the 87 `Health` property. 88 89## Development Details 90There are two significant layers for LED operations. The physical and the 91logical. The LED Group Manager communicates with the physical LED Manager to 92drive the physical LEDs. The logical groups are defined in the machine's 93led.yaml file. LED Group manager consumes this and creates D-Bus/REST 94interfaces for the individual LEDs that are part of the group. 95 96### Defining the physical LED 97 98Physical LED wiring is defined in the `leds` section of the machine's 99[device tree][Kernel ARM DTS]. See the [Palmetto DTS][Palmetto DTS LED] 100as an example. 101 102_Add a fault LED to the device tree with a corresponding gpio pin..._ 103``` 104 leds { 105 compatible = "gpio-leds"; 106 107 fault { 108 gpios = <&gpio ASPEED_GPIO(N, 2) GPIO_ACTIVE_LOW>; 109 }; 110 } 111``` 112 113_The kernel will then create..._ 114 115``` 116 ls -l /sys/class/leds/fault/ 117total 0 118-rw-r--r-- 1 root root 4096 Jun 21 20:04 brightness 119lrwxrwxrwx 1 root root 0 Jun 21 20:29 device -> ../../../leds 120-r--r--r-- 1 root root 4096 Jun 21 20:29 max_brightness 121drwxr-xr-x 2 root root 0 Jun 21 20:29 power 122lrwxrwxrwx 1 root root 0 Jun 21 20:04 subsystem -> ../../../../../class/leds 123-rw-r--r-- 1 root root 4096 Jun 21 20:04 trigger 124-rw-r--r-- 1 root root 4096 Jun 21 20:04 uevent 125``` 126 127### Defining Groups 128An LED Group can contain zero or more LEDs and is defined in the machines 129[led.yaml][LED YAML]. The default one will likely need to be tailored to your 130machines layout. Customized yaml files are placed into the machines specific 131Yocto location. As an example: 132 133``` 134meta-ibm/meta-palmetto/recipes-phosphor/leds/palmetto-led-manager-config/led.yaml 135``` 136 137The parent properties in the yaml file will be created below `/xyz/openbmc_project/led/groups/`. 138The children properties need to map to an LED name in `/sys/class/leds`. 139 140In the example, below two URIs would be created: 141`/xyz/openbmc_project/led/groups/enclosure_fault` and 142`/xyz/openbmc_project/led/groups/lamp_test`. Both act on the same physical 143LED `fault` but do so differently. The lamp_test would also drive a blink 144signal to the physical `power` LED if one was created. 145 146 147``` 148EnclosureFault: 149 fault: 150 Action: 'On' 151 DutyOn: 50 152 Period: 0 153lamp_test: 154 fault: 155 Action: 'Blink' 156 DutyOn: 20 157 Period: 100 158 power: 159 Action: 'Blink' 160 DutyOn: 20 161 Period: 100 162 163``` 164 165### Required Groups 166OpenBMC Architecture requires specific LED Groups to be created and are 167documented in the [D-Bus interface][LED D-Bus README]. 168 169 170## Yocto packaging 1711. Create a tailored LED manager file 172 173 E.g. `meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config-native.bb` 174 ``` 175 SUMMARY = "Phosphor LED Group Management for Romulus" 176 PR = "r1" 177 178 inherit native 179 inherit obmc-phosphor-utils 180 inherit obmc-phosphor-license 181 182 PROVIDES += "virtual/phosphor-led-manager-config-native" 183 184 SRC_URI += "file://led.yaml" 185 S = "${WORKDIR}" 186 187 # Overwrites the default led.yaml 188 do_install() { 189 SRC=${S} 190 DEST=${D}${datadir}/phosphor-led-manager 191 install -D ${SRC}/led.yaml ${DEST}/led.yaml 192 } 193 ``` 1942. Change your machine's preferred provider for the led-manager in the conf file 195 196 E.g. `meta-ibm/meta-romulus/conf/machine/romulus.conf` 197 198 ```PREFERRED_PROVIDER_virtual/phosphor-led-manager-config-native = "romulus-led-manager-config-native"``` 199 200 201[LED D-Bus README]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/README.md 202[LED YAML]: https://github.com/openbmc/phosphor-led-manager/blob/master/led.yaml 203[Kernel ARM DTS]: https://github.com/openbmc/linux/tree/dev-4.19/arch/arm/boot/dts 204[Palmetto DTS LED]: https://github.com/openbmc/linux/blob/dev-4.19/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dts#L45 205