From 4e735960fe5c30536047c53c04afa28285a9f4b3 Mon Sep 17 00:00:00 2001
From: Louis Opter <kalessin@kalessin.fr>
Date: Sat, 8 Aug 2015 17:58:45 -0700
Subject: [PATCH] Document tag/untag and update known issues

---
 README.rst        | 22 +++++++++++++---------
 docs/protocol.rst | 27 ++++++++++++++++++++++++++-
 2 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/README.rst b/README.rst
index 51d0870..f48b9c4 100644
--- a/README.rst
+++ b/README.rst
@@ -82,11 +82,11 @@ Clone this repository and then:
    .../lightsd/build$ make -j5
 
 Finally, to start lightsd with the jsonrpc interface listening on localhost
-port 1234:
+port 1234 and a command pipe named lightsd.cmd:
 
 ::
 
-   .../lightsd/build$ core/lightsd -v info -l ::1:1234
+   .../lightsd/build$ core/lightsd -v info -l ::1:1234 -c lightsd.cmd
 
 lightsd forks in the background by default, display running processes and check
 how we are doing:
@@ -106,18 +106,22 @@ Use the ``-f`` option to run lightsd in the foreground.
 Known issues
 ------------
 
-The grouping (tagging) code of the LIFX White 800 is bugged: after a tagging
-operation the LIFX White 800 keep saying it has no tags. Reboot the bulb to make
-the tags appears.
+The grouping (tagging) code of the LIFX White 800 (and presumably the Color 650
+as well) is bugged: after a tagging operation the LIFX White 800 keep saying it
+has no tags. Reboot the bulb to make the tags appears.
 
 Power ON/OFF are the only commands with auto-retry, i.e: lightsd will keep
 sending the command to the bulb until its state changes. This is not implemented
 (yet) for ``set_light_from_hsbk``, ``set_waveform``, ``tag`` and ``untag``.
 
-While lighsd appears to be pretty stable, if you want to run lightsd in the
-background, I recommend doing so in a processor supervisor (e.g: Supervisor_)
-that can restart lightsd if it crashes. Otherwise, please feel free to report
-crashes to me.
+In general, crappy WiFi network with latency, jitter or packet loss are gonna be
+challenging until lightsd has an auto-retry mechanism, there is also room for
+optimizations in how lightsd communicates with the bulbs.
+
+While lightsd appears to be pretty stable, if you want to run lightsd in the
+background, I recommend doing so in a process supervisor (e.g: Supervisor_) that
+can restart lightsd if it crashes. Otherwise, please feel free to report crashes
+to me.
 
 .. _Supervisor: http://www.supervisord.org/
 
diff --git a/docs/protocol.rst b/docs/protocol.rst
index b200797..8db7e29 100644
--- a/docs/protocol.rst
+++ b/docs/protocol.rst
@@ -12,7 +12,7 @@ Commands that manipulate bulbs will take a *target* argument to define on which
 bulb(s) the operation should apply:
 
 +-----------------------------+-----------------------------------------------+
-| ``\*``                      | targets all bulbs                             |
+| ``*``                       | targets all bulbs                             |
 +-----------------------------+-----------------------------------------------+
 | ``#TagName``                | targets bulbs tagged with *TagName*           |
 +-----------------------------+-----------------------------------------------+
@@ -75,4 +75,29 @@ Available methods
     - power: boolean, true when the bulb is powered on false otherwise;
     - tags: list of tags applied to the bulb (utf-8 encoded strings).
 
+.. function:: tag(target, label)
+
+   Tag (group) the given target bulb(s) with the given label (group name), then
+   label can be used as a target by prefixing it with ``#``.
+
+   To add a device to an existing "group" simply do:
+
+   ::
+
+      tag(["#myexistingtag", "bulbtoadd"], "myexistingtag")
+
+   .. note::
+
+      Notice how ``#`` is prepended to the tag label depending on whether it's
+      used as a target or a regular argument.
+
+.. function:: untag(target, label)
+
+   Remove the given tag from the given target bulb(s). To completely delete a
+   tag (group), simple do:
+
+   ::
+
+      untag("#myexistingtag", "myexistingtag")
+
 .. vim: set tw=80 spelllang=en spell: