More docs work

Also tweaked some defaults to make them safer for default use. It will
complicate things a little, but if I can finish the packaging, not that
much.

blinkenxmas-web.service

@@ -4,7 +4,7 @@ After=network.target local-fs.target
 
 [Service]
 Type=simple
-ExecStart=/usr/local/bin/bxweb
+ExecStart=/usr/local/bin/bxweb --production
 Restart=on-failure
 
 [Install]

blinkenxmas.nginx

@@ -0,0 +1,20 @@
+server {
+    listen 80;
+    listen [::]:80;
+
+    location / {
+        proxy_pass http://localhost:8000/;
+
+        # Limit requests to a reasonable size
+        client_max_body_size 10m;
+        client_body_buffer_size 128k;
+
+        proxy_set_header Host $host;
+        # Not currently used by the application
+        add_header X-Frame-Options "sameorigin";
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Host $server_name;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}

blinkenxmas/default.conf

@@ -9,12 +9,13 @@ topic = blinkenxmas
 
 # The [web] section specifies the address that the web interface should listen
 # to (0.0.0.0 meaning "all addresses" is the default), and what port to use.
-# Please note the default port (80) is privileged. If you do not wish to run
-# the service as root, pick an unprivileged port (>1024).
+# Please note the default port is the unprivileged 8000. To run this
+# application on the standard port, you are recommended to place it behind a
+# reverse proxy like nginx.
 
 [web]
-bind = 0.0.0.0
-port = 80
+bind = 127.0.0.1
+port = 8000
 database = /var/local/cache/blinkenxmas/presets.db
 
 # The [wifi] section provides the SSID and password the Pico should use to
@@ -29,7 +30,7 @@ password = your-wifi-password-here
 # GPIO to use to indicate status (by blinking an LED attached to it); this
 # defaults to "LED" which is the built-in LED on the Pico-W but can be any
 # other unused GPIO number. The "error" setting can be "reset" or "flash"
-# indicating what to do in the case of a fatal error
+# indicating what to do in the case of a fatal error.
 
 [pico]
 status = LED

blinkenxmas/web.py

@@ -33,7 +33,7 @@ def get_web_parser():
         action='store_false')
     web_section.add_argument(
         '--production', section='web', key='production', action='store_true',
-        help="If specified, run in production mode where an internal server "
+        help="if specified, run in production mode where an internal server "
         "error will not terminate the server and will not output a stack "
         "trace (default: no)")
     web_section.add_argument(

docs/api.rst

@@ -4,7 +4,7 @@ API Reference
 
 The Blinken' Xmas code tries to be as reasonably self-contained as possible, to
 avoid too many dependencies in order to make the packaging a bit easier and
-low-maintenance longevity a bit more likely!
+low-maintenance longevity a bit more likely.
 
 The following sections list the various modules in the Python code:
 
@@ -27,4 +27,4 @@ The following sections list the various modules in the Python code:
 
 I'm afraid the Pico-side code is (currently) largely undocumented. However, it
 is much simpler, and if you can understand the Pi-side of the code you'll
-easily handle the Pico side!
+easily handle the Pico side.

docs/blinkenxmas.conf.rst

@@ -0,0 +1,204 @@
+================
+blinkenxmas.conf
+================
+
+All applications in the Blinken' Xmas suite read their configuration from the
+following locations:
+
+* :file:`/usr/local/etc/blinkenxmas.conf`
+
+* :file:`/etc/blinkenxmas.conf`
+
+* :file:`{$XDG_CONFIG_HOME}/blinkenxmas.conf` where $XDG_CONFIG_HOME is
+  typically :file:`~/.config`
+
+If multiple of these exist, they are read in the order above with settings in
+later files overriding settings from earlier ones. The configuration file
+format is based on the common `INI file`_ format.
+
+The following sections document the available settings.
+
+
+[mqtt]
+======
+
+Configures the MQTT broker that :program:`bxweb` and :program:`bxcli` post to,
+and to which the Pico will listen.
+
+host
+    The hostname of the MQTT broker. Even if the broker is present on the local
+    machine, this must be set to a "proper" hostname, i.e. something other than
+    "localhost". Default: "broker"
+
+    This configuration is also used to generate the Pico's configuration, which
+    will need the actual network address.
+
+port
+    The port on which the MQTT broker will be listening. May be specified as an
+    integer or a registered service name. Default: 1833.
+
+topic
+    The topic to which the Pico should subscribe, and to which the web
+    application will publish new animations for the tree to play.
+
+
+[web]
+=====
+
+Settings specific to the :program:`bxweb` application.
+
+bind
+    The address to which :program:`bxweb` should bind and listen for
+    connections. If you are running the application "bare" this should be set
+    to "0.0.0.0" or "::" to bind to all interfaces. If you are using a reverse
+    proxy, this should be set to "127.0.0.1" (the default) or "::1".
+
+port
+    The port on which :program:`bxweb` should listen for connections. If you
+    are running the application "bare" this should be 80 (or 443 if you can be
+    bothered to set up HTTPS for an xmas tree!). If you are running this behind
+    a reverse proxy, this should be set to an unprivileged port like 8000 (the
+    default).
+
+database
+    The path to the SQLite database used by :program:`bxweb` and
+    :program:`bxcli` to store and retrieve preset animations, and tree LED
+    coordinates.
+
+
+[wifi]
+======
+
+Configures the wifi access point that the Pico connects to. Used by
+:program:`bxflash` to generate the Pico's configuration.
+
+ssid
+    The SSID of the wifi access point that the Pico should attempt to connect
+    to on startup.
+
+password
+    The password of the wifi access point that the Pico should use. Currently
+    there is no support for anything other than basic PSK authentication.
+
+
+[pico]
+======
+
+Configuration settings specific to the Pico. These are used by
+:program:`bxflash` to generate the code uploaded to the Pico.
+
+status
+    The GPIO number (or name) of the status LED on the Pico. This is flashed
+    in various patterns to indicate the current state. Defaults to "LED" which
+    is the built-in LED on the Pico W.
+
+error
+    The action to take on a fatal error. May be set to "reset" (the default) to
+    reboot the Pico, or "flash" to terminate and flash the status in a regular
+    pattern. The "flash" setting is primarily intended for debugging as it
+    permits connection to the serial console to query state.
+
+
+[camera]
+========
+
+This section defines the camera used by :program:`bxweb` to calibrate the
+positions of the LEDs on the tree.
+
+type
+    The type of camera available to the system running :program:`bxweb`. Can be
+    set to one of:
+
+    none
+        No camera is available for tree calibration. The default.
+
+    picamera
+        Uses the legacy :mod:`picamera` library to control a Raspberry Pi
+        camera module attached to the local system (which is presumably a
+        Raspberry Pi)
+
+    gstreamer
+        Uses the GStreamer framework to query a V4L2 video source, typically a
+        USB web-camera).
+
+    files
+        Uses a pre-captured set of JPEG images to emulate a camera. Primarily
+        intended for development and testing purposes.
+
+device
+    When *type* is "gstreamer", the path of the V4L2 video source. Defaults to
+    :file:`/dev/video0`
+
+path
+    When *type* is "files", the path of the pre-captured files. See
+    :class:`blinkenxmas.cameras.FilesSource` for further details of the file
+    naming convention expected.
+
+capture
+    The resolution at which to capture images, specified as a "WIDTHxHEIGHT"
+    value, e.g. "1920x1080". For accuracy reasons, this should be set to the
+    native capture resolution of the camera device, e.g. "2592x1944" for a v1
+    Pi camera module.
+
+preview
+    The resolution at which to capture video for the web-based preview,
+    specified as a "WIDTHxHEIGHT" value, e.g. "640x480". For performance
+    reasons, this should generally be set to quite a low resolution.
+
+
+[leds:\*]
+=========
+
+These sections define the various LED strips that are attached to the tree. At
+least 1, and up to 8 of these sections may be defined. The "*" in the section
+title is arbitrary and simply used to distinguish the sections.
+
+driver
+    Set to either "WS2812" or "APA102" depending on the sort of neopixels
+    present in the strip.
+
+pin
+    When *driver* is "WS2812", specifies the GPIO pin connected to the data pin
+    of the neopixels in the strip.
+
+dat, clk
+    When *driver* is "APA102", specifies the GPIO pins connected to the DAT
+    (data) and CLK (clock) pins of the neopixels in the strip, respectively.
+
+count
+    The number of neopixels in the strip. Typically some multiple of 50.
+
+order
+    Specifies the color ordering expected by the neopixels in the strip.
+    Usually "RGB" or "GRB", but any combination of R, G, and B is accepted,
+    e.g. "BGR". If the neopixels include a separate white channel, append "W"
+    to the value, e.g. "RGBW" or "GRBW".
+
+fps
+    The maximum refresh rate to apply to the neopixels in the strip. Defaults
+    to 60.
+
+    .. note::
+
+        Dropping this to 30 can considerably speed up tranmission of animations
+        as it halves the amount of data involved, but with obvious implications
+        for the smoothness of animation.
+
+reversed
+    If "no" (the default), the neopixels are addressed from the "start" of the
+    strip; if "yes", from the end.
+
+    This is primarily useful in non-calibrated installations where you are
+    relying on the position along the strip for certain effects, have multiple
+    strips, and want one strip to "continue" an animation from the top of the
+    tree (the end of another strip) back to the bottom.
+
+
+Example
+=======
+
+.. literalinclude:: ../blinkenxmas/default.conf
+    :language: ini
+    :caption: /etc/blinkenxmas.conf
+
+.. _INI file: https://en.wikipedia.org/wiki/INI_file

docs/bxcli.rst

@@ -1,9 +1,103 @@
+.. program:: bxcli
+
 =====
 bxcli
 =====
 
-.. program:: bxcli
-
-The command line interface for the BlinkenXmas project. Provides a simple
+The command line interface for the Blinken' Xmas project. Provides a simple
 command line which can load or delete an existing preset, set all LEDs to a
 specific color, or set an individual LED to a specified color.
+
+
+Synopsis
+========
+
+::
+
+    bxcli [-h] [--version] [--broker-address ADDR] [--broker-port NUM]
+          [--topic TOPIC] {command} ...
+
+
+Options
+=======
+
+.. option:: -h, --help
+
+    Show the help message and exit
+
+.. option:: --version
+
+    Show program's version number and exit
+
+.. option:: --broker-address ADDR
+
+    The address on which to find the MQTT broker. Default: broker
+
+.. option:: --broker-port NUM
+
+    The port on which to find the MQTT broker. Default: 1883
+
+.. option:: --topic TOPIC
+
+    The topic on which the Pico W is listening for messages. Default: blinkenxmas
+
+.. option:: command
+
+    See `Commands`_ below
+
+
+Commands
+========
+
+help [command]
+    Display help on the specified *command*, or a summary of all commands
+
+off
+    Switch all LEDs off
+
+on {color}
+    Switch all LEDs on with the specified *color*, given as a common CSS3 color
+    name, or an HTML color code in the form #RRGGBB, e.g. #FF0000 for red.
+
+set {index} {color}
+    Set LED *index* to the specified *color*. The *index* is simply an integer
+    number counting from 0..n-1 where *n* is the total number of LEDs present
+    in the tree. The *color* is given as a common CSS3 color name, or an HTML
+    color code in the form #RRGGBB.
+
+list
+    Display the names of all presets currently stored in the database on the
+    terminal.
+
+show {preset}
+    Display the specified *preset* on the tree. Note that preset names
+    containing special characters or spaces will likely need quoting on the
+    command line.
+
+
+Debugging
+=========
+
+The **on** command is particular useful for testing your setup. To ensure your
+power setup is adequate (and adequately isolated), try:
+
+.. code-block:: console
+
+    $ bxcli on "#ffffff"
+
+This should switch all LEDs on at full white (shield your eyes!). If your Pico
+crashes, you are likely using a single supply (or single rail on a single
+supply) for both your LEDs and the Pico. This is likely to fail when there are
+sudden fluctuations in the brightness of the LEDs, leading to brief voltage
+drops on the line.
+
+Assuming everything does light correctly, and the Pico doesn't crash, leave the
+tree fully lit for a minute, and check the heat of the cables running from your
+power supply to the neopixels. If they are too hot to touch, you are strongly
+advised to replace those cables with something thicker.
+
+
+See Also
+========
+
+:doc:`bxweb`, :doc:`bxflash`, :doc:`blinkenxmas.conf`