1# phosphor-led-manager 2 3This project manages LED groups on dbus. Sometimes many LEDs must be driven 4together to indicate some system state. 5 6For example, there can be multiple identify LEDs. When the user wants to 7identify the system, they should all light up together. 8 9## Configuration 10 11The configuration can happen via json or yaml. 12 13### Configuration: LED Priority 14 15Each LED can have "Priority" as "Blink", "Off" or "On". If this property is 16defined, it should be defined on each instance of the LED in the config. 17 18When multiple LED groups are asserted and contain the same LED, "Priority" 19determines the state of the LED. 20 21For example, Group 1 says LED1 should be "Blink", and Group 2 says it should be 22"On". LED1 will then have the state declared in "Priority". 23 24## Configuration: LED Group Priority 25 26Using LED Priority is fine for simple configurations, but when group state needs 27to always be consistent, Group Priority can be used to enforce the consistent 28representation. 29 30The Group `Priority` is optional and a higher priority means that when 2 groups 31are asserted, the one with highest `Priority` will be represented consistently. 32Meaning all its LEDs will have the state as per the configuration. 33 34## Configuration Example with Group Priorities (JSON) 35 36Here we prioritize the locating group above the fault group since locating may 37be required to fix the fault. 38 39So independent of the order that these groups are asserted, if both are 40asserted, "sys_id" should be in "Blink" state. 41 42The "unrelated" group will have the default group priority of 0. 43 44``` 45$ cat example.json 46{ 47 "leds": [ 48 { 49 "group": "enclosure_identify", 50 "Priority": 2, 51 "members": [ 52 { 53 "Name": "sys_id", 54 "Action": "Blink" 55 }, 56 { 57 "Name": "rear_id", 58 "Action": "Blink" 59 } 60 ] 61 }, 62 { 63 "group": "fault", 64 "Priority": 1, 65 "members": [ 66 { 67 "Name": "sys_id", 68 "Action": "On" 69 }, 70 { 71 "Name": "fault", 72 "Action": "On" 73 } 74 ] 75 }, 76 { 77 "group": "unrelated", 78 "members": [ 79 { 80 "Name": "rear_id", 81 "Action": "On" 82 } 83 ] 84 } 85 ] 86} 87``` 88 89### Configuration Example (JSON) 90 91This is our configuration file. It describes 2 LEDs for the 92'_enclosure_identify_' group, with their respective states and duty cycles. 93 94```json 95{ 96 "leds": [ 97 { 98 "group": "enclosure_identify", 99 "members": [ 100 { 101 "Name": "pca955x_front_sys_id0", 102 "Action": "On", 103 "DutyOn": 50, 104 "Period": 0, 105 "Priority": "Blink" 106 }, 107 { 108 "Name": "led_rear_enc_id0", 109 "Action": "On", 110 "DutyOn": 50, 111 "Period": 0, 112 "Priority": "Blink" 113 } 114 ] 115 } 116 ] 117} 118``` 119 120Then start the program with 121 122```text 123~# ./phosphor-led-manager --config example.json 124``` 125 126## Dbus interface 127 128When starting the program, our LED group shows up on dbus. Usually there will be 129many more groups. 130 131```text 132$ busctl tree xyz.openbmc_project.LED.GroupManager 133`- /xyz 134 `- /xyz/openbmc_project 135 `- /xyz/openbmc_project/led 136 `- /xyz/openbmc_project/led/groups 137 `- /xyz/openbmc_project/led/groups/enclosure_identify 138 139 140$ busctl introspect xyz.openbmc_project.LED.GroupManager /xyz/openbmc_project/led/groups/enclosure_identify 141NAME TYPE SIGNATURE RESULT/VALUE FLAGS 142... 143xyz.openbmc_project.Led.Group interface - - - 144.Asserted property b false emits-change writable 145``` 146 147In the above output, the usual org.freedesktop.\* interfaces have been removed 148to keep it readable. 149 150We can now drive the entire group by setting it's 'Asserted' property on dbus. 151 152```text 153$ busctl set-property \ 154xyz.openbmc_project.LED.GroupManager \ 155/xyz/openbmc_project/led/groups/enclosure_identify \ 156xyz.openbmc_project.Led.Group Asserted b true 157``` 158 159The program can then use the _xyz.openbmc_project.Led.Physical_ dbus interface 160exposed by _phosphor-led-sysfs_ to set each LED state. 161 162## How to Build 163 164```text 165meson setup build 166cd build 167ninja 168``` 169