blinkenxmas.conf

All applications in the Blinken’ Xmas suite read their configuration from the following locations:

/usr/local/etc/blinkenxmas.conf
/etc/blinkenxmas.conf
$XDG_CONFIG_HOME/blinkenxmas.conf where $XDG_CONFIG_HOME is typically ~/.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 bxweb and 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 bxweb application.

bind: The address to which 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 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 bxweb and bxcli to store and retrieve preset animations, and tree LED coordinates.

[wifi]

Configures the wifi access point that the Pico connects to. Used by 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 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 bxweb to calibrate the positions of the LEDs on the tree.

type

The type of camera available to the system running bxweb. Can be set to one of:

none: No camera is available for tree calibration. The default.
picamera: Uses the legacy 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 /dev/video0

path

When type is “files”, the path of the pre-captured files. See 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

/etc/blinkenxmas.conf

# The [mqtt] secion details where the MQTT broker can be found, and what topic
# should be used for publication (by the web interface) and subscription (by
# the Pico LED driver).

[mqtt]
host = broker
port = 1883
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 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 = 127.0.0.1
port = 8000
database = /var/local/cache/blinkenxmas/presets.db
docs = https://blinkenxmas.readthedocs.io/en/latest/
source = https://github.com/waveform80/blinkenxmas/

# The [wifi] section provides the SSID and password the Pico should use to
# connect to the local LAN. Please note this section is *only* used by the
# Pico; the web interface uses the host's network configuration.

[wifi]
ssid = your-ssid-here
password = your-wifi-password-here

# The [pico] section provides other Pico-specific settings including which
# 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.

[pico]
status = LED
error = reset

# The [camera] section defines the camera available for calibration of the
# Xmas tree. Valid types are:
#
# * none -- The default; indicates no camera is available for calibration.
#
# * picamera -- This expects a Raspberry Pi camera module which will be
#   accessed via the legacy picamera library. The "capture" key specifies the
#   resolution at which to capture images. The "preview" key specifies the
#   resolution at which to preview images.
#
# * gstreamer -- This expects a V4L2 video source (typically a USB web-camera)
#   which will be accessed via GStreamer. The video source can be manually
#   configured with the "device" key which defaults to /dev/video0. The
#   "capture" and "preview" keys may be specified with this camera too.
#
# * files -- This expects a set of pre-captured JPEG images stored in the
#   specified path with filenames in the format:
#   "angle090_led015_color#ffffff.jpg"; i.e. "angle" followed by the
#   zero-padded angle of capture (0..359), "led" followed by the zero-padded
#   index of the LED (0..999), and "color" followed by color of the LED in the
#   form #RRGGBB. The JPEG files must all have the same resolution, and all
#   expected files must be present (i.e. one image for each angle for each LED
#   for each expected color, even if the LED is not visible from that angle).

[camera]
type = picamera
capture = 2592x1944
preview = 640x480
rotate = 0

type = gstreamer
device = /dev/video0
capture = 960x720
preview = 640x480

type = files
path = /tmp

type = none

# You can specify up to eight [leds:x] sections. At least one section must be
# specified. The "x" is arbitrary and only serves to uniquely identify each
# section.
#
# Each [leds:x] section specifies a separate strip of LEDs that the Pico will
# drive. Within each section, the following settings may be specified (settings
# with a * suffix must be specified):
#
# driver* -- This must be WS2812 or APA102 depending on the protocol expected
# by the strip
#
# count* -- The number of LEDs in the strip
#
# fps -- The framerate at which to drive the LEDs. Defaults to 60
#
# reversed -- If "no" (the default), the LEDs in the strip will be numbered
# from their connection point "outward". Otherwise, they will be numbered
# "inward"; this only matters for certain animations
#
# order* -- The order the strip expects colors to be transmitted. Must be one
# of RGB, RBG, GRB, GBR, BRG, BGR, or any of these with a "W" suffix (e.g.
# RGBW) if the strip has four LEDs per segment
#
# pin* -- This must be included if "driver" is WS2812, and specifies the GPIO
# pin to which the strip is connected on the Pico
#
# clk* dat* -- These must be included if "driver" is APA102, and specify the
# GPIO pins which will be used for the "clock" and "data" lines for this strip
# on the Pico

[leds:1]
driver = WS2812
count = 50
fps = 60
order = GRB
pin = 13

[leds:2]
driver = WS2812
count = 50
fps = 60
reversed = yes
order = RGBW
pin = 12

[leds:3]
driver = APA102
count = 50
order = RGB
dat = 15
clk = 16