Skip to content

Latest commit

 

History

History
62 lines (47 loc) · 5.76 KB

README.md

File metadata and controls

62 lines (47 loc) · 5.76 KB
Raw

mqttt - MQTT Terminal

MQTT is a real backbone of IoT. Lighweight, scalable, popular, etc. If you're IoT fanatic, you've perhaps collected a decent set of MQTT tools in your workbench. Me too. But I was always missing a portable, standalone, small, always-on display that could connect to MQTT broker and show the circulating messages. Yeah, I know... I can fire up MQTT.fx or XXX (enter here your preference) on my desktop. But this is not always handy or comfortable.

Therefore here you go... MQTT Terminal is a small, relatively dumb, standalone device to display rolling MQTT messages. It can be build with Raqspberry Pi Zero W (and any other single board computer/SBC) and 3.5" (or bigger) LCD. You can place it on your desk, next to your laptop, and discretely watch whether MQTT messaging works as expected. Great for targeted troubleshooting or ad hoc diagnosis.

Screenshots of MQTT Terminal with different fonts and sizes:

| | | |

You can configure:

  • display type (usually 3.5" LCD via /dev/fb1 video framebuffer, but the code can be also run on Linux and MS Windows desktops, etc.)
  • LCD resolution (tested with 3.5" 480x320 LCD, but the code will work for smaller and bigger displays)
  • font type (font name for system fonts, font location for other fonts)
  • font size (separately for title and for MQTT messages)
  • colors for background and message font
  • number of displayed MQTT messages (one message equals one line of text), usually between 8 and 15
  • rotation 'upside down' (180 degree) for reverted LCD screens. Just remove "rotate_upside_down" line for the straight (not reverted) screen.

HARDWARE

Raspberry Pi Zero W is perhaps the most optimal (cost and performance) platform. It's even too beefy for such easy task, but come on... You can spend $9 for RPi or $3 on ESP8266 - small difference for a singular DIY quantities. And with RPi you have a comfort of full Linux distribution, fully functional version of Python, flawless WiFi, etc.

For the display, you can use any small LCD screen HAT you wish. It has to work with Raspberry Pi, of course. But this is the only limitation. MQTT Terminal uses framebuffer for graphics so it DOES NOT need X Server to be installed. When selecting OS distribution for your Raspberry Pi, do not install fully featured desktop version. Choose server flavor. It is much lighter anyway.

INSTALLATION AND MANUAL RUN

On Linux, install Paho MQTT Python client library and some fonts (assuming you run headless server without X Server and without any fancy fonts, incl. system fonts). Then just clone this repository, configure mqtttcfg.json file and run the code. I propose to make './bin' directory to keep this code there.

> sudo pip3 install paho-mqtt
> sudo apt-get install ttf-mscorefonts-installer fonts-liberation
> mkdir bin
> cd bin
> git clone https://github.com/DarS007/mqttt.git
# CONFIGURE mqtttcfg.json FILE AND RUN THE APP (WITH sudo)
> sudo ./mqttt.py

AUTOMATIC STARTUP

Pygame is a great framework for use not only with full (but complex) X-Windows environment, but also with a simple graphics framebuffer ('fbcon', 'directfb', 'svgalib'). Most of the Pygame drawing operations take place on a screen (Pygame term), which is rendered on a specific display (another Pygame term, see: http://www.pygame.org/docs/ref/display.html). You must remember, however, that you're obliged to keep the needed user context for the screen, display and framebuffer. This is quite easy for a regular use, when you log in to your Linux account and manually run your Python code, so Pygame captures 'your' framebuffer for the display. Things get complicated when you try to achieve the same with systemd startup scripts:

  • You can try to autostart your user code with 'User=root' option in systemd script, but then Pygame will not know the user context for the framebuffer.
  • You can try to autostart with 'User=XXX' (enter your user name here), but then Pygame will not start due to unsufficient priviledges ('root' access is needed to manipulate the framebuffer).

Googling confirmed that such problems were quite common, and many people expressed their frustration. Solution? Two-stage startup process able to both create the user context and provide the 'root' priviledges. Our systemd startup script had to be rewritten to become two-staged:

  • first stage: systemd startup script is invoked with 'User=XXX' option, so the user context is set for future actions. The systemd startup script is written in such a way that it invokes additional bash script and not the main Pygame application (as expected in the typical scenario)
  • second stage: the additional bash script adds 'sudo' in front of Pygame app invocation to ensure 'root' priviledges.

COPY STARTUP SCRIPTS

Such two-stages startup principle has been applied to 'mqttt' (Pygame app). You need to manually copy both startup scripts mqttt.service and mqttt_script.sh to /lib/systemd/system/ directory.

ENABLE 'MQTTT' SERVICE

Then use 'systemctl' command to enable, run or stop the mqttt service:

> sudo systemctl enable mqttt   - ENABLE THE MQTTT SERVICE
> sudo systemctl status mqttt   - CHECK STATUS (and possible errors)
> sudo systemctl start mqttt    - START APPLICATION/SERVICE
> sudo systemctl stop mqttt     - STOP APPLICATION/SERVICE

TO DO

  • MQTT authentication - it is currently lacking, as the code was developed for in-house usage where local MQTT broker was open to everyone (in the subnet)