This repo contains the (python) code to run Leezenflow.
Copyright (C) 2021-2023 bCyber GmbH
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/.
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
- 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
andsudo 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 directoryrpi-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.
-
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
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.
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