Reading Time: 6 minutesIn this tutorial we’re going to use a popular messaging protocol, MQTT (Message Queuing Telemetry Transport). With MQTT we will set up a simple do-not-disturb sign that you can trigger with a single key press and customise to your heart’s content.
Step 01: Prepare Raspberry Pi
We’re using two Raspberry Pi Zero W computers for this project, although it will work with any recent model. For both, we recommend installing Raspberry Pi OS Lite (magpi.cc/software) as we don’t need a desktop interface. Make sure both devices are working and connected to the same network. We also recommend setting their host names by running sudo raspi-config at the command line, then going to System Options > Hostname. We chose ‘busybot’ for the sign and ‘buttonbot’ for the controller and that’s how we’ll refer to them throughout this tutorial. Finally, make sure everything is up-to-date. Enter these commands:
sudo apt update
sudo apt full-upgrade
You should be able to ping one device from the other. On ‘busybot’ Raspberry Pi Zero W, enter:
ping buttonbot.local
You should should get a response from ‘buttonbot’ Raspberry Pi Zero W.
Step 02: Install the Scroll pHAT HD and diffuser
We’re going to set up the display first. Pimoroni’s Scroll pHAT HD is a display made up of 17×7 pixels (119 total) and comes with a Python library that does all the hard work of displaying and scrolling text for us. The pHAT form factor makes it just the right size for a display, but of course you can adopt this tutorial to any display you like. You’ll need to solder the 40-pin header to the display and also add a reciprocal header to ‘busybot’ Raspberry Pi if it doesn’t already have one. Before assembling them together, screw on the diffuser, which will make the display much easier to read. Now, with Raspberry Pi powered off, carefully connect the Scroll pHAT HD.
Step 03: Set up the display software
It’s time to make sure our display is working before we go any further. Fortunately, Pimoroni has created an install script for us. At the command line, run the following:
curl https://get.pimoroni.com/scrollphathd | bash
Make sure you do the ‘Full Install’ when the option is presented. This will set up Raspberry Pi so it can communicate with the display and install all the Python libraries we need. Take a look at Pimoroni’s GitHub (magpi.cc/scrollphatgit) for more information on installation.
Once the install has finished, we can test things out. Reboot, then try this on the command line:
cd ~/Pimoroni/scrollphathd/examples
python3 swirl.py
See a pretty pattern? Then you’re ready to proceed. Have fun with the other examples in the directory; they’re a great source of inspiration.
Step 04: Introducing MQTT
Our buttonbot and busybot are going to need to talk to each other over the network. One of the easiest, and most popular, ways to do this is the MQTT protocol. It uses a pub/sub model (publisher / subscriber) to process messages. An MQTT server (the ‘broker’) receives messages from ‘publishers’ that are then transmitted to ‘subscribers’. These are organised by ‘topic’. The biggest advantage is that publishers don’t need to understand or even be aware of the subscribers, they just need to speak MQTT. Don’t worry if this is confusing; working through the tutorial will make things clearer.
Step 05: Mosquitto
For our system to work, you need an MQTT server (or ‘broker’) to handle the messages. This can be anywhere on your network, but for the purposes of the tutorial we’ll install it on the same ‘busybot’ Raspberry Pi driving the display. MQTT software tends to be very ‘lightweight’, so a Raspberry Pi Zero W can easily handle being the server as well as a publisher. Mosquitto is probably the most popular set of MQTT tools. Installation is straightforward, too. Enter this at the command line:
sudo apt install mosquitto mosquitto-clients
sudo pip3 install paho-mqtt
The broker will be automatically installed as a service and always be running in the background. We’ve also installed Paho, a popular Python library for implementing MQTT.
Step 06: Busybot’s code
The code for this project does two main jobs: listens to the MQTT server for new messages, and then takes those messages and scrolls them on the display. You can enter the code shown here or get the files from magpi.cc/busybotgit. We need the code to be running all the time. To do this, create a new file from the command line:
sudo nano /usr/lib/systemd/busybot.service
Enter the code from busybot.service. (Change the paths if you’ve created the code elsewhere.) Save the file (CTRL+X and then Y), then enter these commands:
sudo systemctl enable /usr/lib/systemd/busybot.service
sudo systemctl start busybot
Step 07: Testing time
Let’s confirm that the code is working. Using the Paho MQTT libraries, the code subscribes to the MQTT topic ‘busybot’ on the broker. Whenever anything publishes a line of text to that topic, busybot will be notified, the text delivered and then displayed. We can check everything is working using the Mosquitto command line publishing tool:
mosquitto_pub -h localhost -t busybot -m "Hello from MagPi"
If you see the messages scrolling across, then everything is working. Send any message you wish, or a blank space to clear the display.
Step 08: Assemble the Keybow
Now we have our display working, it’s time to turn our attention to sending the messages. MQTT is widely supported and you can get clients for almost every platform and programming language in common use. That means we can send messages to the display from pretty much anywhere. In this tutorial, we’re going to use Pimoroni’s Keybow interface to provide a quick way of setting messages. On the second ‘buttonbot’ Raspberry Pi WH, assemble the Keybow as instructed at magpi.cc/assemblekeybowmini, but don’t install Keybow OS – we’re sticking with Raspberry Pi OS Lite.
Step 09: Keybow setup
We’ll now add some code to send messages to the MQTT broker when buttons are pressed. First, from the command line, we need to install some dependencies on buttonbot:
sudo apt install python3-pip git
sudo pip3 install keybow paho-mqtt
Now get the code from GitHub:
cd
git clone https://github.com/mrpjevans/busybot.git
We can now test the Keybow with a simple example:
cd ~/busybot
python3 test_keybow.py
Press the keys. Do they all light up? Then all is well.
Step 10: Keybow code
In the busybot directory, have a look at buttonbot.py. You’ll also need to change the name of the MQTT broker and/or topic if you’ve used something different.
We need to make sure the code is always running, just like busybot. Again, we’ll create a service to do this. From buttonbot’s command line, go through the process in Step 6 to create a service file and enable it. Just make sure you change the
ExecStart
line to:
ExecStart=/usr/bin/python3 /home/pi/busybot/buttonbot.py
Save the file and enable it as before.
Step 11: Testing and tinkering
Everything should now be ready. With both Raspberry Pi Zero computers running, try pressing a key on the Keybow. A message will now scroll across the display on the other Raspberry Pi Zero. Make sure all three keys work. You’re now ready to start customising the system to your own needs. If you edit buttonbot.py, you’ll see some documented options for changing the messages and the colours of the keys. Free free to experiment, make changes and make this code your own. If you need more than three messages, see if you can alter the code to support key press combinations, which would give you up to seven options.
Step 12: Python vs C++
As the display doesn’t ‘know’ about buttonbot’s existence, it means that anything capable of speaking MQTT can send messages to busybot to set the scrolling text. It could be done from the command line or when a certain event happens. If you’ve been following the Home Assistant (HA) series in The MagPi magazine, then you may be interested to know that HA speaks MQTT, so the display could be tied to a temperature or motion sensor. Have fun dreaming up new ideas for your display.
