Operate SSD1306 OLED via NavQPlus

Connecting a small display to the NavQPlus to show information such as IP address and link status.

Introduction

This tutorial demonstrates how to write text on SSD1306 OLED display modules using the I2C interface of NavQPlus board.

Items needed

S. No.	Name	Quantity
1	NavQPlus	1
2	Micro SD Card (only for normal NavQPlus software image)	1
3	USB-UART serial debugger	1
4	USB-A (Male) to TTL 6-Pin Serial Adaptor Cable (Female)	1
5	Cat6a (Male) ix Industrial to RJ45 (Male) Ethernet Cable	1
6	USB-C (Male) to USB-A (Male) Cable	1
7	SSD1306 OLED (Preferrably 128×64 or 128×32)	1
8	JST GH 1.25mm Pitch 6 Pin Cable (Female to Female)	2
9	Jumper wires	4

Hardware procedure

You will need to create a custom cable to connect the OLED 4 pin signals to a JST-GH 6 pin connector to plug into the NavQPlus. NOTE: An off the shelf cable is not provided, but it is simple to make your own according to the table below.

Connections from SSD1306 OLED to J12 Port on NavQPlus

OLED pin header #	Name	JST-GH 6 Pin number of J12 on NavQPlus
1	Voltage	1
2	Ground	6
3	Clock	3
4	SDA	2

Block diagram of NavQPlus attached to OLED via I2C interface complete setup

Software procedure

Overview

In this example software, a daemon service polls the desired network interface every one second for its link status and IP address and publishes the same on an OLED display.

Any of the standard network interfaces may be specified when starting the daemon.

Prerequisites

If not already running the standard NavQPlus Ubuntu POC image, then flash the following image on the micro SDcard of NavQPlus: Ubuntu 22.04 for NavQPlus or greater. Click on the desired image and download the ".wic.bz2" file. Extract it and flash the resultant ".wic" image on the micro SDcard. More detailed instructions are provided elsewhere in this gitbook.

NavQPlus board setup

Install python libraries

On the NavQPlus board, install the python packages luma and pillow. They are required as prerequisites by our application. They are a driver for the OLED and also a small python imaging library.

Perform the following steps to clone the project and set-up the application.

sudo pip install smbus2 luma.oled luma.core pillow  # installing prerequisites.

cd ~
git clone [e-mail]:NXPHoverGames/NavQPlus-apps.git  # cloning the repo.
cd NavQPlus-apps/ssd1306_oled

Review the python code directly in the Git repo here: https://github.com/NXPHoverGames/NavQPlus-apps

Create Daemon

Create a daemon service that will invoke our application in the background, by running the following steps. The command "systemctl start" starts a new instance of the application in the background,, "systemctl status" returns the running status and latest logs of the said instance of the application and "systemctl stop" terminates the said instance of the daemon service.

Rememeber, in order to access the service using "systemctl status" and "systemctl stop" commands, the parameters must be the same as the ones used to start the service. (using "systemctl start").

Otherwise a different instance (the one corresponding to the passed parameters) of the service will be accessed.

sudo mv ssd1306_interface_status@.service /etc/systemd/system
sudo systemctl daemon-reload

sudo systemctl start $(systemd-escape --template ssd1306_interface_status@.service "<interface> <display width> <display height>")

sudo systemctl status $(systemd-escape --template ssd1306_interface_status@.service "<interface> <display width> <display height>")

In the provided example python code, it does include a check whereby if the Daemon attempts to write to a non existent OLED, then the write command will fail and the daemon will stop itself automatically.

Example 1: 128x32 OLED display

Use the command below to track the "usb0" interface and the resolution of your OLED module is 128×32.

This is the OLED display shown below in the image "Display B: SSD1306 128×32"

sudo systemctl start $(systemd-escape --template ssd1306_interface_status@.service "usb0 128 32")

Display A: SSD1306 128×32

Example 2: 128x64 OLED display

Use the command below to track the "usb0" interface and the resolution of your OLED module is 128×64.

This is the OLED display shown below in the image "Display B: SSD1306 128×64"

sudo systemctl start $(systemd-escape --template ssd1306_interface_status@.service "usb0 128 64")

Display B: SSD1306 128×64

Stopping the interface

To change interface name, display width and/or display height, or stop the service, run the following "systemctl stop" command,

you may then restart the service using "systemctl start" command using new parameters.

This is relevant to when you want to track a different network interface, or if you want to use an OLED module that has a different resolution than the one you were using before.

sudo systemctl stop  $(systemd-escape --template ssd1306_interface_status@.service "<interface> <display width> <display height>")

Demonstration with Videos

Displaying network and system status

Our application prints the link status and ip address of the specified network every one second on the SSD1306 OLED display. To change the link status of the network interface to UP or DOWN, you may use the following ifconfig commands. Note: when the link status is DOWN, the ip address is shown as NULL.

sudo ifconfig <interface name> up
sudo ifconfig <interface name> down

If the text is not displayed on the OLED screen, please retry after 5-10 seconds.

Demonstration Video - Displaying System Status (YouTube)

Displaying Network and System Status of NavQPlus on SSD1306 OLED display

Displaying GIF and PNG files

Animations and images could be displayed on the SSD1306 OLED module using the luma.examples companion repository. Kindly refer the following demonstration video for the same.

In our demonstration we only tested with displaying GIF and PNG files.

Demonstration Video Displaying GIF and PNG, (YouTube)

Displaying GIF and PNG files on SSD1306 OLED connected to NavQPlus