Leezenflow Source Code

This repo contains the (python) code to run Leezenflow.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Requirements

The hardware setup is described in detail in this guide. The basics are:

Raspberry PI 3 Model B+
Adafruit RGB Matrix HAT + RTC for Raspberry Pi
32x32 RGB LED Matrix Panel - 5mm Pitch
64x32 RGB LED Matrix - 5mm pitch

To test the setup we recommend to check out: https://github.com/hzeller/rpi-rgb-led-matrix.
As stated in the docs, you should disable sound: https://github.com/hzeller/rpi-rgb-led-matrix#bad-interaction-with-sound and bridge GPIO Pins 4 and 18 as documented here: https://github.com/hzeller/rpi-rgb-led-matrix#improving-flicker

Source: https://github.com/hzeller/rpi-rgb-led-matrix/blob/master/img/adafruit-mod.jpg

Setup on Raspberry PI

For initializing your Raspberry Pi with an operating system, install the official Raspberry PI imager (we used version v.1.7.2) on a computer with a microSD card reader. Plug in an empty microSD card and select Raspberry Pi OS (other) -> Raspberry Raspberry Pi OS Lite (32-Bit). We used version 2022-04-04. Make sure that you activate SSH.
Find out the ip address of your Raspberry Pi and connect to it using ssh pi@IPADDRESS.
Install git, e.g. using sudo apt update and sudo apt install git.
Install pip, e.g. using sudo apt-get install python3-pip
Clone rpi-rgb-led-matrix to e.g. /home/pi/
You can adjust the Makefile if you made any hardware modifications. See: https://github.com/hzeller/rpi-rgb-led-matrix/tree/master/bindings/python
Build the library. First, change directories into rpi-rgb-led-matrix/bindings/python/. Then:

sudo apt-get update && sudo apt-get install python3-dev python3-pillow -y
make build-python PYTHON=$(command -v python3)
sudo make install-python PYTHON=$(command -v python3)

Deactivate the sound module as described in the readme of https://github.com/hzeller/rpi-rgb-led-matrix.
Check an example by running sudo python runtext.py in directory rpi-rgb-led-matrix/bindings/python/samples/
Another example: sudo python pulsing-brightness.py --led-gpio-mapping=adafruit-hat-pwm --led-cols=96 --led-rows=32
Let's add the Leezenflow code: Clone this repo this to e.g. /home/pi/
Install Python library to receive MQTT messages: sudo pip install -r requirements.txt

The implemention assumes you have made the "adafruit-hat-pwm" modification to your hardware.

Development setup

Create virtual environment: python -m venv venv
Install dependencies (within virtual environment):
```
pip install -r requirements.txt
```
Install leezenflow package in editable mode (within virtual environment):
```
pip install -e .
```
(optional) Run unit tests, which are located in folder tests:
```
pytest tests
```

(optional) You can see a demo animation in your terminal with:

sudo python leezenflow-code/scripts/animation_demo_moving.py --display terminal

Terminal output

If you want to see the output in your terminal, you need to use a terminal that supports true color. We suggest iTerm2 or Kitty. You should also zoom out (or reduce the font size) quite a bit, depending on your display size, before starting, to see the full animation.

Production usage (on Raspberry PI)

Run the following commands in the leezenflow-code directory:

sudo pip install -r requirements.txt
sudo pip install -e .

Use sudo python scripts/main.py --help to get an overview over command line options.

Setup the main.py script as service such that Leezenflow runs on start:

cd /etc/systemd/system
Create file: sudo touch leezenflow.service
Edit file: sudo nano leezenflow.service
Enter (for example) the following:

[Unit]
Description=Start leezenflow
After=multi-user.target
[Service]
WorkingDirectory=/home/pi/leezenflow-code
ExecStart=/usr/bin/python -u /home/pi/leezenflow-code/scripts/main.py --your-settings
User=root
[Install]
WantedBy=multi-user.target

Reload: sudo systemctl daemon-reload
After testing the service with sudo systemctl start leezenflow.service, run: sudo systemctl enable leezenflow.service to enable automatic startup after a reboot.
The service can be stopped with: sudo systemctl stop leezenflow.service
Reminder: Do not forget to use the python -u (as used above) flag in your service definition to prevent logging problems