oled-status

Status message logger for embedded systems equipped with a small OLED display.

OLED Status has two parts: the server module that drives the display and the client library that pushes data to the display. The server is meant to be run as a module and requires the following Setup procedure. The client is designed to be embedded in other apps running on the device to show relevant information on an otherwise embedded app.

Setup

OLED Status requires both hardware and software setup to work properly. This setup is required to use OLED Status on a display attached to the device.

Hardware

A Single Board Computer running Linux with I²C support connected to a 0.91" 128x32 OLED Display driven by a SSD1306. OLED Status was developed and has only been tested on a Raspberry Pi 4 with a Treedix Display Module.

• Displays
  • Treedix 0.91" OLED Display Module (Blue/White)
  • Adafruit Monochrome 0.91" 128x32 I2C OLED Display - STEMMA QT / Qwiic
  • Adafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry Pi
• Single Board Computer
  • Raspberry Pi 4

For wiring instructions, see Adafruit's Python Wiring Guide.

Software

Adafruit's Circuit Python compatability layer, Blinka, drives the OLED display and can be a bit tricky to install. OLED was developed and testes only on Ubuntu 20.04 but should be fully compatiable with any Blinka supported OS.

Ubuntu

1. Update Ubuntu and it's packages:

sudo apt update
sudo apt upgrade

2. Ubuntu doesn't ship with a compatiable version of Python, install Python 3.9+ and it's dependencies:

sudo apt install python3.9 python3.9-venv python3.9-dev

3. Ubuntu resticts access to the I²C bus to root users by default. Create a udev rule to allow all users access automatically at boot by writing the following file at /etc/udev/rules.d/i2c.rules:

ACTION=="add", KERNEL=="i2c-[0-1]*", MODE="0666"

• Learn more from this StackExchange Answer

4. Reboot for the udev rule to take effect:

sudo reboot

5. Optionally setup a virtual environment:

python3.9 -m venv ./venv
. venv/bin/activate

The remainder of the setup will be handled by pip when OLED Status is installed.

Raspberry Pi OS

See Adafruit's Circuit Python Installation Guide and then setup a virtual environment if desired.

Installation

OLED Status is distributed via Github Releases and PyPI.

Server

The server should be installed and set to autorun once, multiple client libraries and processes can connect to a single server instance.

1. Install the OLED Status Server from PyPI:

pip install oled-status[server]

• Note this also installs the relevant Circuit Python dependecies to communicate with the display. If it fails to install, try again after running pip install wheel to add support for bdist_wheel.

At this point the server can be started with python -m oled_status.server and the OLED Display will be initialized. It's likly preferable that the server be automatically started at bootup, in which case continue:

2. Create a service to automatically start the OLED Status Server, this varies depending on if a virtual environemnt (recommended) is in use. These are the instructions for using a virtual environment:
   1. Create a start-oled-status-server.sh script which activates the virtual environment and then starts the OLED Status Server:

   #!/bin/bash
   cd <directory>
   . venv/bin/activate
   python -m oled_status.server

   2. Modify the script so it is executable: sudo chmod x+ start-oled-status-server.sh
   3. Create a service the run the script at startup by writing the following file at /etc/systemd/system/oled-status.service:

   [Unit]
   Description=OLED Status Server
   StartLimitIntervalSec=0
   
   [Service]
   Type=simple
   Restart=always
   RestartSec=1
   User=<username>
   ExecStart=/path/to/start-oled-status-server.sh
   
   [Install]
   WantedBy=multi-user.target
   

   4. Enable the startup service: systemctl enable oled-status
   5. Reboot

Client

The client libary is to be used by any locally running application that wishes to display data on the OLED Display.

pip install oled-status

Use

The OLED Status provides a single Status Class which when intantiated allows for messages to be added to, modified on, and removed from the OLED Display. The client communicates with the server over local port 6533 on seperate threads to prevent status updates from blocking execution.

When there are multiple messages to be displayed on the OLED Display, they are automatically cycled through, each showing for 5 seconds in the order they were recieved. Messages that are updated retain their original position in the cycle. As a result of the cycle, messages are not instantly displayed.

from oled_status import Status

# Publish a new message
message = Status('Heading', 'Message Contents')

# Update a message
message.update('Updated Message')

# Clear a message
message.clear()

Note The OLED Display is tiny, messages that are longer than about 14 uppercase letters will be truncated.