Firmware Engineering Part 3: OLED Display

The temperature/humidity sensor works. Currently, this device communicates with a website and shares data over MQTT. Next, it would be nice to improve the code. We could make it more interactive, for example with an OLED. This is one of the Wokwi's parts available. The OLED we will use is the Adafruit SSD1306 a 128x64 dot matrix. And I have a link for some reference material. Always read the documentation.

We can import this component on Wokwi, and hook up the respective wires to ground, the 3V pin, and others.

To make it easy, here is the updated diagram.json file. The parts are a bit disorganized.

{
  "version": 1,
  "author": "Henry Meier",
  "editor": "wokwi",
  "parts": [
    { "type": "board-esp32-devkit-c-v4", "id": "esp", "top": -37.58, "left": -96.37, "attrs": {} },
    {
      "type": "wokwi-dht22",
      "id": "dht1",
      "top": -172.5,
      "left": 196.2,
      "attrs": { "humidity": "77.5" }
    },
    { "type": "board-ssd1306", "id": "oled1", "top": -131.26, "left": 19.43, "attrs": {} }
  ],
  "connections": [
    [ "esp:TX", "$serialMonitor:RX", "", [] ],
    [ "esp:RX", "$serialMonitor:TX", "", [] ],
    [ "dht1:VCC", "esp:3V3", "red", [ "v109.3", "h-170.36", "v-200.78" ] ],
    [ "dht1:SDA", "esp:15", "green", [ "v0" ] ],
    [ "dht1:GND", "esp:GND.1", "black", [ "v99.7", "h-189.56", "v-66.38" ] ],
    [ "esp:TX", "$serialMonitor:RX", "", [] ],
    [ "esp:RX", "$serialMonitor:TX", "", [] ],
    [ "oled1:SCL", "esp:22", "green", [ "h96.3", "v164.02" ] ],
    [ "oled1:SDA", "esp:21", "blue", [ "v-19.2", "h-124.73" ] ],
    [ "oled1:GND", "esp:GND.2", "black", [ "v-67.2", "h-96" ] ],
    [ "oled1:VCC", "esp:3V3", "red", [ "v-28.8", "h0.15", "v-76.8", "h-201.75" ] ]
  ],
  "dependencies": {}
}        

The circuit now looks like this. Notice the shared red and black wires, we also utilize two other pins on the ESP32.

We need to update the assignment of ESP32 pins to reflect our new circuit. After the initialization, add the following code.

# ESP32 Pin assignment 
i2c = I2C(0, scl=Pin(22), sda=Pin(21))

oled_width = 128
oled_height = 64
oled = ssd1306.SSD1306_I2C(oled_width, oled_height, i2c)        

We also need to import the respective library for this new component. There is a MicroPython driver for this specific component.

Now this is a long file so Save this as ssd1306.py in the Wokwi editor.

I also found this driver file on GitHub.

#MicroPython SSD1306 OLED driver, I2C and SPI interfaces created by Adafruit

import time
import framebuf

# register definitions
SET_CONTRAST        = const(0x81)
SET_ENTIRE_ON       = const(0xa4)
SET_NORM_INV        = const(0xa6)
SET_DISP            = const(0xae)
SET_MEM_ADDR        = const(0x20)
SET_COL_ADDR        = const(0x21)
SET_PAGE_ADDR       = const(0x22)
SET_DISP_START_LINE = const(0x40)
SET_SEG_REMAP       = const(0xa0)
SET_MUX_RATIO       = const(0xa8)
SET_COM_OUT_DIR     = const(0xc0)
SET_DISP_OFFSET     = const(0xd3)
SET_COM_PIN_CFG     = const(0xda)
SET_DISP_CLK_DIV    = const(0xd5)
SET_PRECHARGE       = const(0xd9)
SET_VCOM_DESEL      = const(0xdb)
SET_CHARGE_PUMP     = const(0x8d)


class SSD1306:
    def __init__(self, width, height, external_vcc):
        self.width = width
        self.height = height
        self.external_vcc = external_vcc
        self.pages = self.height // 8
        # Note the subclass must initialize self.framebuf to a framebuffer.
        # This is necessary because the underlying data buffer is different
        # between I2C and SPI implementations (I2C needs an extra byte).
        self.poweron()
        self.init_display()

    def init_display(self):
        for cmd in (
            SET_DISP | 0x00, # off
            # address setting
            SET_MEM_ADDR, 0x00, # horizontal
            # resolution and layout
            SET_DISP_START_LINE | 0x00,
            SET_SEG_REMAP | 0x01, # column addr 127 mapped to SEG0
            SET_MUX_RATIO, self.height - 1,
            SET_COM_OUT_DIR | 0x08, # scan from COM[N] to COM0
            SET_DISP_OFFSET, 0x00,
            SET_COM_PIN_CFG, 0x02 if self.height == 32 else 0x12,
            # timing and driving scheme
            SET_DISP_CLK_DIV, 0x80,
            SET_PRECHARGE, 0x22 if self.external_vcc else 0xf1,
            SET_VCOM_DESEL, 0x30, # 0.83*Vcc
            # display
            SET_CONTRAST, 0xff, # maximum
            SET_ENTIRE_ON, # output follows RAM contents
            SET_NORM_INV, # not inverted
            # charge pump
            SET_CHARGE_PUMP, 0x10 if self.external_vcc else 0x14,
            SET_DISP | 0x01): # on
            self.write_cmd(cmd)
        self.fill(0)
        self.show()

    def poweroff(self):
        self.write_cmd(SET_DISP | 0x00)

    def contrast(self, contrast):
        self.write_cmd(SET_CONTRAST)
        self.write_cmd(contrast)

    def invert(self, invert):
        self.write_cmd(SET_NORM_INV | (invert & 1))

    def show(self):
        x0 = 0
        x1 = self.width - 1
        if self.width == 64:
            # displays with width of 64 pixels are shifted by 32
            x0 += 32
            x1 += 32
        self.write_cmd(SET_COL_ADDR)
        self.write_cmd(x0)
        self.write_cmd(x1)
        self.write_cmd(SET_PAGE_ADDR)
        self.write_cmd(0)
        self.write_cmd(self.pages - 1)
        self.write_framebuf()

    def fill(self, col):
        self.framebuf.fill(col)

    def pixel(self, x, y, col):
        self.framebuf.pixel(x, y, col)

    def scroll(self, dx, dy):
        self.framebuf.scroll(dx, dy)

    def text(self, string, x, y, col=1):
        self.framebuf.text(string, x, y, col)


class SSD1306_I2C(SSD1306):
    def __init__(self, width, height, i2c, addr=0x3c, external_vcc=False):
        self.i2c = i2c
        self.addr = addr
        self.temp = bytearray(2)
        # Add an extra byte to the data buffer to hold an I2C data/command byte
        # to use hardware-compatible I2C transactions.  A memoryview of the
        # buffer is used to mask this byte from the framebuffer operations
        # (without a major memory hit as memoryview doesn't copy to a separate
        # buffer).
        self.buffer = bytearray(((height // 8) * width) + 1)
        self.buffer[0] = 0x40  # Set first byte of data buffer to Co=0, D/C=1
        self.framebuf = framebuf.FrameBuffer1(memoryview(self.buffer)[1:], width, height)
        super().__init__(width, height, external_vcc)

    def write_cmd(self, cmd):
        self.temp[0] = 0x80 # Co=1, D/C#=0
        self.temp[1] = cmd
        self.i2c.writeto(self.addr, self.temp)

    def write_framebuf(self):
        # Blast out the frame buffer using a single I2C transaction to support
        # hardware I2C interfaces.
        self.i2c.writeto(self.addr, self.buffer)

    def poweron(self):
        pass


class SSD1306_SPI(SSD1306):
    def __init__(self, width, height, spi, dc, res, cs, external_vcc=False):
        self.rate = 10 * 1024 * 1024
        dc.init(dc.OUT, value=0)
        res.init(res.OUT, value=0)
        cs.init(cs.OUT, value=1)
        self.spi = spi
        self.dc = dc
        self.res = res
        self.cs = cs
        self.buffer = bytearray((height // 8) * width)
        self.framebuf = framebuf.FrameBuffer1(self.buffer, width, height)
        super().__init__(width, height, external_vcc)

    def write_cmd(self, cmd):
        self.spi.init(baudrate=self.rate, polarity=0, phase=0)
        self.cs.high()
        self.dc.low()
        self.cs.low()
        self.spi.write(bytearray([cmd]))
        self.cs.high()

    def write_framebuf(self):
        self.spi.init(baudrate=self.rate, polarity=0, phase=0)
        self.cs.high()
        self.dc.high()
        self.cs.low()
        self.spi.write(self.buffer)
        self.cs.high()

    def poweron(self):
        self.res.high()
        time.sleep_ms(1)
        self.res.low()
        time.sleep_ms(10)
        self.res.high()        

And in main.py, we can import this file easily. Import the new library at the top of the code, and the 12C library for communication.

from machine import Pin, I2C
import ssd1306        

Now to utilize this OLED in our main.py program, there are preset methods for interfacing with the OLED easily.

Lets try to indicate on the OLED when the ESP32 connects to WiFi.

print("Connecting to WiFi", end="")
sta_if = network.WLAN(network.STA_IF)
sta_if.active(True)
sta_if.connect('Wokwi-GUEST', '')
while not sta_if.isconnected():
    print(".", end="")
    utime.sleep(0.1)
print(" Connected!")
oled.text('Connected!', 10, 10)      #new code here
oled.show()        

You should see the text display properly within Wokwi. It's like we have a print() statement for our OLED.

Now for MicroPython, we need to clear the OLED properly. Some Stack Overflow research stated that we can properly clear with.

oled.fill(0)        

We can utilize this to clear the OLED and print the temperature and humidity data. I was able to insert this is the area where new data is compared to previous data.

prev_weather = ""
while True:
    print("Measuring weather conditions... ", end="")
    sensor.measure()

    timestamp_utc = get_utc_timestamp()
    message = ujson.dumps({
        "sensor_id": MQTT_CLIENT_ID,
        "temp": sensor.temperature(),
        "humidity": sensor.humidity(),
        "timestamp_utc": timestamp_utc
    })
    
    if message != prev_weather:
        print("Updated!")
        print("Reporting to MQTT topic {}: {}".format(MQTT_TOPIC, message))
        oled.fill(0)
        oled.text("{}: {}".format(sensor.humidity(), sensor.temperature()), 10, 10)      
        oled.show()
        client.publish(MQTT_TOPIC, message)
        prev_weather = message
    else:
        print("No change")
    utime.sleep(10)  # Sleep for 5 minutes (300 seconds)        

When re-running the simulation, we should see the reflected temperatures on the display. This makes temperature and humidity data much more interactive.

I re-organized the code for the sensor a lot better. In the new code, it shows the initial attempt to connect to Wifi and the MQTT server. I also updated the display to show organized data with the timestamp, and to update accordingly with new data. I'm very pleased with how it's operating.

import network
import utime
from machine import Pin
import dht
import ujson
import ubinascii
import os
from umqtt.simple import MQTTClient
from machine import Pin, I2C
import ssd1306

def generate_sensor_id():
    random_id = ubinascii.hexlify(os.urandom(4)).decode()
    return f"{random_id}"

def get_utc_timestamp():
    return utime.time()


MQTT_CLIENT_ID = generate_sensor_id()
MQTT_BROKER = "broker.hivemq.com"
MQTT_USER = ""
MQTT_PASSWORD = ""
MQTT_TOPIC = "solar1"


sensor = dht.DHT22(Pin(15))


i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled_width = 128
oled_height = 64
oled = ssd1306.SSD1306_I2C(oled_width, oled_height, i2c)

# Connect to WiFi
print("Connecting to WiFi", end="")
sta_if = network.WLAN(network.STA_IF)
sta_if.active(True)
sta_if.connect('Wokwi-GUEST', '')
while not sta_if.isconnected():
    print(".", end="")
    utime.sleep(0.1)
print(" Connected!")

# Display WiFi connection status
oled.fill(0)
oled.text('WiFi Connected!', 0, 0)
oled.show()

# Connect to MQTT
print("Connecting to MQTT server... ", end="")
client = MQTTClient(MQTT_CLIENT_ID, MQTT_BROKER, user=MQTT_USER, password=MQTT_PASSWORD)
client.connect()
print("Connected to MQTT server")

# Display MQTT connection status
oled.fill(0)
oled.text('MQTT Connected!', 0, 10)
oled.show()
utime.sleep(2)

prev_weather = ""

while True:
    print("Measuring weather conditions... ", end="")
    sensor.measure()
    temperature = sensor.temperature()
    humidity = sensor.humidity()
    timestamp_utc = get_utc_timestamp()
    message = ujson.dumps({
        "sensor_id": MQTT_CLIENT_ID,
        "temp": temperature,
        "humidity": humidity,
        "timestamp_utc": timestamp_utc
    })

    if message != prev_weather:
        print("Updated!")
        print("Reporting to MQTT topic {}: {}".format(MQTT_TOPIC, message))
        oled.fill(0)
        oled.text('Temp: {:.1f} C'.format(temperature), 0, 0)
        oled.text('Humidity: {:.1f} %'.format(humidity), 0, 10)
        oled.text('Time: {}'.format(timestamp_utc), 0, 20)
        oled.show()
        client.publish(MQTT_TOPIC, message)
        prev_weather = message
    else:
        print("No change")

    utime.sleep(10)  # Sleep for 10 seconds
        

Wokwi is a free website, and has many interesting simulations of electronic components. I honestly couldn't believe that this works so well and can imitate a real OLED.

It's very cool to look at the lists of projects that people around the world have created. A similar project to our our own actually connects to an API and downloads the price of Bitcoin, displaying it on the screen. These cheap ESP32 micro controllers can handle quite a bit of code and can be programmed in numerous languages.