Mercurial > louis > mq > lightsd
changeset 400:da42466a7c5e
finish docs patch
| author | Louis Opter <kalessin@kalessin.fr> |
|---|---|
| date | Sun, 27 Dec 2015 14:41:57 +0100 |
| parents | c8da8c535829 |
| children | ef034165bff3 |
| files | docs_improvements.patch series |
| diffstat | 2 files changed, 0 insertions(+), 316 deletions(-) [+] |
line wrap: on
line diff
--- a/docs_improvements.patch Sun Dec 27 14:36:12 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,315 +0,0 @@ -# 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,192 @@ -+Contributing to lightsd -+======================= -+ -+lightsd is open-source_ software licensed under the GPLv3_ (see `Rationale for -+the GPLv3`_). 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 [#]_. 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. -+ -+.. [#] When motion is detected you want to turn the lights immediatly not in 100 -+ or more milliseconds. -+.. [#] This is actually `already happening`_. -+ -+.. _already happening: https://community.lifx.com/t/lightsd-a-daemon-with-a-json-rpc-api-to-control-your-bulbs/446/41 -+.. _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 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 also used as a test runner. -+ -+lightsd coding style is: -+ -+- overall mostly `K&R`_/1TBS_; -+- tabs are 4 spaces; -+- C++ style comments; -+- 80 columns max (kinda flexible in the headers); -+- 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, it should make the style a non-issue. -+ -+.. _FPU: https://en.wikipedia.org/wiki/Floating-point_unit -+.. _CMake: https://cmake.org/overview/ -+.. _K&R: https://en.wikipedia.org/wiki/Indent_style#K.26R_style -+.. _1TBS: https://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS -+.. _clang format: http://clang.llvm.org/docs/ClangFormat.html -+.. _astyle: http://astyle.sourceforge.net/astyle.html -+ -+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/README.rst b/README.rst ---- a/README.rst -+++ b/README.rst -@@ -77,4 +77,9 @@ - Feel free to reach out via email or irc (kalessin on freenode, insist if I don't - reply). As the project name implies, I'm fairly interested in other smart bulbs. - -+Check out the `contribution guide`_ for the vision behind the project and how to -+contribute. -+ -+.. _contribution guide: https://github.com/lopter/lightsd/blob/master/CONTRIBUTING.rst -+ - .. 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: