Add README.md
Explaining the high level workings of this project.
Change-Id: I066820dc2f7b09081385d3111d3e1beee46b7d8f
Signed-off-by: Alexander Hansen <alexander.hansen@9elements.com>
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..93ee8af
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+# phosphor-led-manager
+
+This project manages LED groups on dbus. Sometimes many LEDs must be driven
+together to indicate some system state.
+
+For example, there can be multiple identify LEDs. When the user wants to
+identify the system, they should all light up together.
+
+## Configuration
+
+The configuration can happen via json or yaml.
+
+## Configuration Example (JSON)
+
+This is our configuration file. It describes 2 LEDs for the
+'_enclosure_identify_' group, with their respective states and duty cycles.
+
+```
+$ cat example.json
+{
+ "leds": [
+ {
+ "group": "enclosure_identify",
+ "members": [
+ {
+ "Name": "pca955x_front_sys_id0",
+ "Action": "On",
+ "DutyOn": 50,
+ "Period": 0,
+ "Priority": "Blink"
+ },
+ {
+ "Name": "led_rear_enc_id0",
+ "Action": "On",
+ "DutyOn": 50,
+ "Period": 0,
+ "Priority": "Blink"
+ }
+ ]
+ }
+ ]
+}
+```
+
+Then start the program with
+
+```
+$ ./phosphor-led-manager --config example.json
+```
+
+## Dbus interface
+
+When starting the program, our LED group shows up on dbus. Usually there will be
+many more groups.
+
+```
+$ busctl tree xyz.openbmc_project.LED.GroupManager
+`- /xyz
+ `- /xyz/openbmc_project
+ `- /xyz/openbmc_project/led
+ `- /xyz/openbmc_project/led/groups
+ `- /xyz/openbmc_project/led/groups/enclosure_identify
+
+
+$ busctl introspect xyz.openbmc_project.LED.GroupManager /xyz/openbmc_project/led/groups/enclosure_identify
+NAME TYPE SIGNATURE RESULT/VALUE FLAGS
+...
+xyz.openbmc_project.Led.Group interface - - -
+.Asserted property b false emits-change writable
+```
+
+In the above output, the usual org.freedesktop.\* interfaces have been removed
+to keep it readable.
+
+We can now drive the entire group by setting it's 'Asserted' property on dbus.
+
+```
+$ busctl set-property \
+xyz.openbmc_project.LED.GroupManager \
+/xyz/openbmc_project/led/groups/enclosure_identify \
+xyz.openbmc_project.Led.Group Asserted b true
+```
+
+The program can then use the _xyz.openbmc_project.Led.Physical_ dbus interface
+exposed by _phosphor-led-sysfs_ to set each LED state.
+
+## How to Build
+
+```
+meson setup build
+cd build
+ninja
+```