An application to display a variety of effects on the Raspberry Pi led-shim from Pimoroni.
The effects are based on the examples given in the base library plus some additions from my fork.
- Binary Clock - Shows hours, minutes and seconds.
- Candle - A flickering candle.
- CheerLights - Synchronize with the CheerLights "Internet of Things" project.
- Coloured Lights - Simple coloured lights like Xmas lights.
- Digital Rain - Cut price Matrix effect.
- Gradient Graph - A moving colour gradient determined by the height of a sine wave.
- Rainbow - A slowly moving rainbow effect.
- Random Blink - Some random blinking.
- Solid Colours - A basic effect which just shows a sequence of solid colours.
If you have more than one Pi with an led-shim you can use the lead/follow commands to share options and perform a simple synchronised start across them. Be sure to start the follow instances before the lead.
Install on Raspbian using:
pip3 install ledshimdemo
Or update using:
pip3 install -U ledshimdemo
$ ledshimdemo --help
Usage: ledshimdemo [OPTIONS] COMMAND [ARGS]...
Show various effects on one or more Raspberry Pi's with Pimoroni LED
shim's.
Use the 'display' command for a single Pi. For multiple Pi's one must use
the 'lead' command and the others the 'follow' command. Ensure you start
the followers before starting the lead.
To limit the effects shown use the effect-list option to list the effects
available then add them to the command line as required. Otherwise all
effects will be shown.
Options:
--version Show the version and exit.
-e, --effect-list List the effects available and exit.
-l, --log-level [DEBUG|VERBOSE|INFO|WARNING]
Show additional logging information.
[default: INFO]
--help Show this message and exit.
Commands:
display Display the effects on a single Pi
follow Follow a lead instance.
lead Act as a lead for other instances to follow.
$ ledshimdemo display --help
Usage: ledshimdemo display [OPTIONS] [EFFECTS]...
Display the effects on a single Pi
Options:
-p, --parade [CYCLE|RANDOM] How the effects are displayed. [default:
CYCLE]
-d, --duration INTEGER RANGE How long to display each effect for, in
seconds (1-180). [default: 10]
-r, --repeat INTEGER RANGE How many times to run the effects before
stopping (1-240). [default: 1]
-b, --brightness INTEGER RANGE How bright the effects will be (1-10).
[default: 8]
-i, --invert Change the display orientation.
--help Show this message and exit.
$ ledshimdmeo follow --help
Usage: ledshimdemo follow [OPTIONS] IP_ADDRESS
Follow a lead instance.
Options:
-o, --port INTEGER RANGE Set the port number used for syncing. [default:
5556]
--help Show this message and exit.
$ ledshimdemo lead --help
Usage: ledshimdemo lead [OPTIONS] IP_ADDRESS [EFFECTS]...
Act as a lead for other instances to follow.
Options:
-p, --parade [CYCLE|RANDOM] How the effects are displayed. [default:
CYCLE]
-d, --duration INTEGER RANGE How long to display each effect for, in
seconds (1-180). [default: 10]
-r, --repeat INTEGER RANGE How many times to run the effects before
stopping (1-240). [default: 1]
-b, --brightness INTEGER RANGE How bright the effects will be (1-10).
[default: 8]
-i, --invert Change the display orientation.
-o, --port INTEGER RANGE Set the port number used for syncing.
[default: 5556]
--help Show this message and exit.
Sample output with the default options:
$ ledshimdemo display
2019-08-31 15:47:36,864 - INFO - Effect Options(parade=CYCLE, duration=10 secs, repeat=1, brightness=8, invert=False, effects=ALL)
2019-08-31 15:47:36,864 - INFO - Effect: BinaryClock - Shows hours, minutes and seconds. Update Frequency: 1 secs
2019-08-31 15:47:47,185 - INFO - Effect: Candle - A flickering candle. Update Frequency: 0.01 secs
2019-08-31 15:47:57,208 - INFO - Effect: CheerLights - Synchronize with the CheerLights "Internet of Things" project. Update Frequency: 5 secs
2019-08-31 15:48:07,745 - INFO - Effect: ColouredLights - Simple coloured lights like Xmas lights. Update Frequency: 0.5 secs
2019-08-31 15:48:17,817 - INFO - Effect: DigitalRain - Cut price Matrix effect. Update Frequency: 0.02 secs
2019-08-31 15:48:27,820 - INFO - Effect: GradientGraph - Sine wave colour gradient effect. Update Frequency: 0.01 secs
2019-08-31 15:48:37,826 - INFO - Effect: Rainbow - A slowly moving rainbow. Update Frequency: 0.01 secs
2019-08-31 15:48:47,861 - INFO - Effect: RandomBlink - Some random blinking. Update Frequency: 0.05 secs
2019-08-31 15:48:57,875 - INFO - Effect: SolidColours - A sequence of solid colours. Update Frequency: 0.5 secs
If you see the error ModuleNotFoundError: No module named 'smbus' you need to run the following install:
sudo apt-get install python3-smbus
The led-shim also requires the I2C interface to be enabled so if you see a message Make sure you've enabled i2c in your Raspberry Pi configuration. you need to run the following command:
sudo raspi-config
Then from the menu select 5. Interface Options and then P5 I2C. Select Yes to enable the interface and then restart you Pi.
However, if anything is going to cause a problem trying to run ledshimdemo it will be NumPy which is used by a couple of the
demos. The NumPy package is included in most builds of Raspbian, but installed with apt-get, this then causes problems if
anything tries to install a different version with pip3. For this reason ledshimdemo includes a dependency on an older version,
or later, hoping to pick up the global installed one. If you get an issue it's worh trying to uninstalling any pip3 version and
then installing the apt-get version using:
pip3 uninstall numpy
sudo apt-get install python3-numpy
Development is done in a branch and a pull request opened which will trigger the GitHub Actions Test & QA workflow. Once this is
passing the pull request can be used to merge the branch into master. Creating a release will then trigger a build and upload to
PyPi using the GitHub Actions Upload to PyPi workflow.
This project is definitely over-engineered and somewhat laboured for what it actually does because it's being used as a learning exercise.
The application has a number of output logging levels built into it, including a custom VERBOSE level, to show some of the inner workings. This is just because.
The effects are loaded dynamically using a mechanism loosely based on code from this Python3 factory pattern example.
The code coverage for this project is a good example of why measuring unit test coverage can be a misleading indicator of quality. Whilst it does have plenty of unit tests those for the effects are mostly simple smoke tests which show that the code will run. They don't actually confirm that the effects are producing the desired output.
The development work for this project was done using PyCharm on an Intel x64 machine, as the project was designed to be run on an ARM based Raspberry Pi only a source distribution is uploaded to PyPi. However, when installing under Raspbian it should install the ARM wheel from PiWheels making the installation much faster. See the PiWheels FAQ for more information.
The synchronisation using the lead/follow commands is very basic, yes the effect options set for the lead are distributed to the follow instances but there is only a primitive trigger to try and start the displays together and there is no heartbeat to try to keep them in sync. If you run with more than about 10 repeat iterations you'll soon see the displays go out of sync.