Mercurial > louis > mq > lightsd
changeset 398:b290ad1e2b30
wip
| author | Louis Opter <kalessin@kalessin.fr> |
|---|---|
| date | Sun, 27 Dec 2015 12:59:23 +0100 |
| parents | a907d149e72b |
| children | c8da8c535829 |
| files | docs_fixes.patch docs_improvements.patch series |
| diffstat | 3 files changed, 301 insertions(+), 59 deletions(-) [+] |
line wrap: on
line diff
--- a/docs_fixes.patch Thu Dec 17 01:41:29 2015 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,58 +0,0 @@ -# HG changeset patch -# Parent f78f899bf1808b4441034cf3d4be9028e60b57bc - -diff --git a/docs/first-steps.rst b/docs/first-steps.rst ---- a/docs/first-steps.rst -+++ b/docs/first-steps.rst -@@ -228,6 +228,12 @@ - - examples/toggle - -+Here is the source code of this example, it uses a small client —lightsc.sh— the -+next section covers it: -+ -+.. literalinclude:: ../examples/toggle -+ :language: sh -+ - .. _examples: - - Using lightsc.sh -@@ -279,6 +285,8 @@ - - Build a batch request manually: - -+.. pygmentize sucks on heredocs: -+ - :: - - tee `lightsc_get_pipe` <<EOF -diff --git a/docs/installation.rst b/docs/installation.rst ---- a/docs/installation.rst -+++ b/docs/installation.rst -@@ -94,13 +94,13 @@ - - .. note:: Those instructions have been tested on Debian Wheezy & Jessie. - --Install the following requirements: -+Install the following packages: - - :: - - build-essential cmake libevent-dev git ca-certificates ipython3 fakeroot wget devscripts debhelper - --Download and extract the release: -+Download and extract lightsd: - - .. parsed-literal:: - -@@ -130,8 +130,8 @@ - - .. note:: - -- If you are not using sudo replace ``$USER`` by your regular non-root -- username: -+ If you are *not using sudo* on your system replace ``$USER`` by your regular -+ non-root username: - - :: -
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs_improvements.patch Sun Dec 27 12:59:23 2015 +0100 @@ -0,0 +1,300 @@ +# HG changeset patch +# Parent f78f899bf1808b4441034cf3d4be9028e60b57bc +Docs improvements, add a contribution guide kinda doubles as a manifesto + +diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst +new file mode 100644 +--- /dev/null ++++ b/CONTRIBUTING.rst +@@ -0,0 +1,190 @@ ++Contributing to lightsd ++======================= ++ ++lightsd is open-source_ software licensed under the GPLv3_ (see ++gplv3_rationale_). This basically means that you can use lightsd free of charge, ++as you see fit, for an unlimited amount of time, no ads, no evaluation period, ++no activation key. ++ ++Likewise, you can also download and consult the entire source code of lightsd. ++Finally, you are welcome to modify lightsd but the GPLv3 forces you to make ++those changes public if you decide to share your modified version of lightsd ++with other people or companies. ++ ++This document describes how to share your modifications directly with lightsd's ++developers so that they can be incorporated, distributed and maintained with the ++rest of the project. ++ ++.. _open-source: http://opensource.org/faq#osd ++.. _GPLv3: https://www.gnu.org/licenses/quick-guide-gplv3.html ++ ++Project governance ++------------------ ++ ++lightsd is a personal project. Its primary goal is for its author_ to learn and ++have fun. At the end of the day, no-one tells me what I should do and how I ++should do it. I get to say the last word [#]_. ++ ++I don't have any timeline nor any pressure and I will have no problem saying no ++to any feature or contribution that doesn't fit my vision of the project or ++doesn't reach the quality bar I set for myself and the project. ++ ++Do not take a "no" personally and hold me accountable for constructive feedback. ++ ++.. _author: mailto:Louis Opter <kalessin@kalessin.fr> ++ ++.. [#] Ultimately, this is not true: the GPL license has the last word. ++ ++Project goals ++------------- ++ ++The current goal is to be the best and most correct implementation of the `LIFX ++LAN protocol`_. ++ ++Unlike other projects around LIFX bulbs, lightsd is a background service (daemon ++in the Unix terminology). It allows lightsd to act as a proxy for the bulbs and ++to report or change the status of the bulbs in near real time. Those two ++properties are fundamental to the project: ++ ++- being able to work as a proxy makes lightsd easy to extend to other IoT ++ protocols. It also allows network isolation; ++- being as real time as possible will, I hope, pave the way for new kind of ++ usages. For example lightsd is currently is used to pair LIFX bulbs with ++ motion sensors, such system requires low latency [latency]_. Integrations with ++ video games also come to mind and may require low latency. ++ ++lightsd took the bold choice of being implemented in pure C. C simply is the ++most portable language both from a tool-chain perspective but also from a ++hardware perspective: anything that can run a very stripped down version of ++Linux should be able to run lightsd successfully. Portability is a goal and I ++hope that it will also unlock new kind of usage & interactions. A corollary to ++portability is that lightsd should have the shortest startup and discovery time ++possible: lightsd might not always run as a background service. ++ ++lightsd must work out of the box and be installable by a high school student who ++discovered command line interfaces last week. When documenting something assume ++readers kinda know how to copy paste commands in a terminal emulator and install ++packages on their system but nothing more. Do not assume they know how to ++properly administrate their system, lightsd should be an opportunity to learn ++that and inspire the user to learn more. Using lightsd has to be a rewarding ++experience. ++ ++.. [latency] When motion is detected you want to turn the lights immediatly not ++ in 100 or more milliseconds. ++ ++.. _LIFX LAN protocol: http://lan.developer.lifx.com/ ++ ++Non-goals ++--------- ++ ++HTTP is overused, misused and is a non-goal, sorry. ++ ++However, I'm very willing to have a lightsd client that can run inside web ++browsers. I'm willing to embed a dead simple HTTP server within lightsd to serve ++that web application. Communication between the web application and lightsd ++cannot use HTTP, I believe this is possible using some newer Javascript ++technologies; worst-case websockets may be an acceptable compromise. ++ ++Reporting bugs ++-------------- ++ ++I can be joined via email, via IRC in `#lightsd`_ on Freenode, you can also post ++in this topic_ and if you feel comfortable writing bug reports you can directly ++open an issue on Github_. ++ ++.. _#lightsd: irc://chat.freenode.net/#lightsd ++.. _topic: https://community.lifx.com/t/lightsd-a-daemon-with-a-json-rpc-api-to-control-your-bulbs/446/ ++.. _Github: https://github.com/lopter/lightsd/issues/new ++ ++Submitting contributions ++------------------------ ++ ++Submitting a contribution is pretty much like a reporting a bug. At this point, ++I'll deal with pretty much any non f'ed-up format. What really matters to me is ++the content: make sure your understand how the project is governed and what the ++goals are. ++ ++It's probably better to start a discussion with me before implementing ++something. Feel free to pick an open bug and work on it, if you're not ++comfortable in C I'll guide you through the whole thing. I'm ready to work with ++motivated beginners, and whatever the outcome is (i.e: your contribution being ++merged or not), I'll make sure it's constructive and that you learn something ++useful. ++ ++I'm trying to make this a cool project to learn programming: in the middle you ++have lightsd: a traditional UNIX daemon written in C that doesn't compromise on ++modernity (modular approach, evented I/O, unit-tested, fast and lightweight, ++highly portable, well integrated in modern init systems). On the left you have ++those bulbs that I'm sure could run cool home-brewed firmware and use some ++reverse-engineering. And on the right you have this JSON-RPC API that can be ++used to implement any kind of cool client. ++ ++In other words, by simply using lightsd you are already contributing. For ++example a better LIFX firmware would be an awesome contribution. A cool mobile ++application would be even better. ++ ++Coding style ++------------ ++ ++lightsd is written in C99, C11 doesn't bring much and will make us incompatible ++with some platforms (e.g: gcc 4.2 and Microsoft is known to really lag behind on ++C standards support). ++ ++lightsd must work on 32/64 bits and little/big endian architectures. ++ ++lightsd is designed to work on machines without an FPU_, do not use floats ++unless there is no other choice. ++ ++lightsd is portable and uses CMake_ to introspect the system it's being built ++on. Currently supported systems are: Linux, BSD and Darwin (Mac OS X), new ++features must work on all three of them. ++ ++New code must be unit-tested, CMake is used as a test runner. ++ ++lightsd coding style is: ++ ++- tabs are 4 spaces; ++- C++ style comments; ++- 80 columns max (kinda flexible in the headers); ++- braces are mandatory around any conditional (rationale: see previous SSL ++ vulnerabilities, also Go's style); ++- don't use typedef (rationale: reduces readability, typedefs in C are really ++ only useful on integers for things like ``pid_t``, where an int isn't the ++ right semantic or for fixed-width integers); ++- no includes in the headers (rationale: avoid fucked-up circular dependencies ++ scenarios); ++- includes order: alphabetically sorted system includes (with ``sys/`` includes ++ first however), then libraries includes, then local includes; ++- when defining a function the return type and the function name must be on two ++ different lines (rationale: make searching a function definition really easy ++ with the ``^`` regular expression anchor). ++ ++Overall, just be consistent with the existing coding-style, I'll setup clang ++format or astyle_ when I get a chance to make the style a non-issue. ++ ++.. _FPU: https://en.wikipedia.org/wiki/Floating-point_unit ++.. _CMake: https://cmake.org/overview/ ++.. _astyle: http://astyle.sourceforge.net/astyle.html ++ ++.. _gplv3_rationale: ++ ++Rationale for the GPLv3 ++----------------------- ++ ++I chose the GPLv3 license for lightsd because it's a personal project and I ++don't want lightsd to be used then modified to make a new (or improve an ++existing) product behind closed doors. Moreover, I work on lightsd on my free ++time and I don't want my time to be used by a company for free. ++ ++That said I'd like to make lightsd easy to integrate (i.e: without any ++modification) in a closed source context. For example I'm perfectly fine if ++lightsd is bundled with a mobile application as long as it's not modified and ++that application stays transparent on its use of lightsd and links to lightsd's ++homepage. ++ ++In the unlikely event that lightsd gains significant adoption I want it to be ++the reference and unique implementation of its own protocol but also a reference ++implementation for the other protocols it implements. I hope that the GPL will ++be a good incentive to achieve that goal. ++ ++.. vim: set tw=80 spelllang=en spell: +diff --git a/docs/first-steps.rst b/docs/first-steps.rst +--- a/docs/first-steps.rst ++++ b/docs/first-steps.rst +@@ -228,6 +228,12 @@ + + examples/toggle + ++Here is the source code of this example, it uses a small client —lightsc.sh— the ++next section covers it: ++ ++.. literalinclude:: ../examples/toggle ++ :language: sh ++ + .. _examples: + + Using lightsc.sh +@@ -279,6 +285,8 @@ + + Build a batch request manually: + ++.. pygmentize sucks on heredocs: ++ + :: + + tee `lightsc_get_pipe` <<EOF +diff --git a/docs/installation.rst b/docs/installation.rst +--- a/docs/installation.rst ++++ b/docs/installation.rst +@@ -94,13 +94,13 @@ + + .. note:: Those instructions have been tested on Debian Wheezy & Jessie. + +-Install the following requirements: ++Install the following packages: + + :: + + build-essential cmake libevent-dev git ca-certificates ipython3 fakeroot wget devscripts debhelper + +-Download and extract the release: ++Download and extract lightsd: + + .. parsed-literal:: + +@@ -130,8 +130,8 @@ + + .. note:: + +- If you are not using sudo replace ``$USER`` by your regular non-root +- username: ++ If you are *not using sudo* on your system replace ``$USER`` by your regular ++ non-root username: + + :: + +diff --git a/docs/known-issues.rst b/docs/known-issues.rst +--- a/docs/known-issues.rst ++++ b/docs/known-issues.rst +@@ -1,21 +1,34 @@ + Known issues + ============ + +-Severe issues have been seen with firmwares released with new bulbs models +-during 2015. lightsd appears to make those bulbs crash [#]_ after some period of +-time; original bulbs with older firmware will not have those issues. It's +-interesting to note that both original and newer bulbs are served the same +-traffic by lightsd which might point out regressions in LIFX's firmwares. ++All LIFX bulbs –except for the original model released with their kickstarter ++campaign (called the “Original 1000”)– are suffering from a critical firmware ++bug [#]_. Under some specific and unknown Wi-Fi conditions LIFX bulbs will ++crash, forcing you to turn them off and then back on using a physical light ++switch. + +-.. [#] Forcing you to turn them off and back on using a regular light switch. ++Crashed LIFX bulbs will show up as unavailable [#]_ in the LIFX mobile ++application and they will be missing in lightsd's ``get_light_state`` result ++list. ++ ++The only known workaround at this time is to try different Wi-Fi channel, you ++might find one that doesn't trigger the bug for your bulbs and radio-frequency ++environment (LIFX bulbs are running in the very busy 2.4GHz band). ++ ++.. [#] More accurately a firmware bug within the Qalcomm Atheros chip upon which ++ all LIFX products released since 2015 are built. ++ ++.. [#] Kinda like this emoji: ⛔️. ++ ++---- + + 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``, ``set_label``, ``tag`` and + ``untag``. + +-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 ++In general, crappy Wi-Fi 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. + + .. vim: set tw=80 spelllang=en spell: