Package: oled-status
oled-statusStatus 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.SetupOLED 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.HardwareA Single Board Computer running Linux with I2C 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.DisplaysTreedix 0.91" OLED Display Module (Blue/White)Adafruit Monochrome 0.91" 128x32 I2C OLED Display - STEMMA QT / QwiicAdafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry PiSingle Board ComputerRaspberry Pi 4For wiring instructions, seeAdafruit's Python Wiring Guide.SoftwareAdafruit'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.UbuntuUpdate Ubuntu and it's packages:sudoaptupdate
sudoaptupgradeUbuntu doesn't ship with a compatiable version of Python, install Python 3.9+ and it's dependencies:sudoaptinstallpython3.9python3.9-venvpython3.9-devUbuntu resticts access to the I2C 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 fromthis StackExchange AnswerReboot for the udev rule to take effect:sudorebootOptionally setup a virtual environment:python3.9-mvenv./venv
.venv/bin/activateThe remainder of the setup will be handled bypipwhen OLED Status is installed.Raspberry Pi OSSeeAdafruit's Circuit Python Installation Guideand then setup a virtual environment if desired.InstallationOLED Status is distributed viaGithub ReleasesandPyPI.ServerThe server should be installed and set to autorunonce, multiple client libraries and processes can connect to a single server instance.Install the OLED Status Server from PyPI:pipinstalloled-status[server]Notethis also installs the relevant Circuit Python dependecies to communicate with the display.  If it fails to install, try again after runningpip install wheelto add support forbdist_wheel.At this point the server can be started withpython -m oled_status.serverand the OLED Display will be initialized.  It's likly preferable that the server be automatically started at bootup, in which case continue: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:Create astart-oled-status-server.shscript which activates the virtual environment and then starts the OLED Status Server:#!/bin/bashcd<directory>
.venv/bin/activate
python-moled_status.serverModify the script so it is executable:sudo chmod x+ start-oled-status-server.shCreate 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.targetEnable the startup service:systemctl enable oled-statusRebootClientThe client libary is to be used by any locally running application that wishes to display data on the OLED Display.pipinstalloled-statusUseThe OLED Status provides a singleStatusClass 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 port6533on 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.fromoled_statusimportStatus# Publish a new messagemessage=Status('Heading','Message Contents')# Update a messagemessage.update('Updated Message')# Clear a messagemessage.clear()NoteThe OLED Display is tiny, messages that are longer than about 14 uppercase letters will be truncated.