Making an ESP8266-based LED clock

Index, feed.

32x16 LED display, ESP8266-MAX7129-LED-CLOCK Wemos clone

This is more or less a follow-up to "Tinkering with a LED matrix: first steps."

Motivation

Compared to last time's project that was based on Arduino Uno and a Chip single-board computer, I wanted to improve a few things:

• Reliability: the Arduino Uno clone apparently died on me — I did not investigate this very deeply — and, on dirty shutdowns, which are a fact of life, the Chip computers tend to get their storage corrupted in a way that eventually prevents booting. More over, the company making the hardware, Next Thing Co., appears to have died in 2018, making it a bad fit for any future projects. I don't know how reliable the ESP8266 Wemos module will prove, but I'm thinking that one less embedded component is probably good.

• Bulkiness: the LED display is about 128x32 mm (plus a little on the end where the connectors are), whereas the Chip computer is 60x40 mm and the Arduino Uno is about 68x53 mm, making them too large to conceal behind the display.

Parts

• ESP8266 Wemos clone: as of 2020-02, this sells for about $3.56 on ebay.ca, or $6 on amazon.ca;

• 32x8 MAX7219-based LED display (four daisy-chained 8x8 modules; one MAX7219 chip for each): as of 2020-02, those sell for about $6.60 on ebay.ca, or $10 on amazon.ca.

The former is a microcontroller with both UDP-capable Wi-Fi and GPIO pins. It is programmable using the Arduino IDE, through it USB port, which also provides a serial console when the sketch runs; a useful debugging feature. It can be powered from USB (5V), and its I/O voltage is 3.3V.

The latter uses a simple serial protocol to let any device capable of digital output control an array of four square 64-LED displays (daisy-chaining allows using fewer or more modules, using one chip for each). It operates at 5V.

Together, these can form a display that can be controlled remotely through UDP over WiFi. While the logic levels are theoretically incompatible and should require a level shifter, as the ESP outputs 3.3V for logic high and the MAX expects at least 3.5V, the combination appears to work well in practice, perhaps because the actual implementations are more tolerant than the datasheets guarantee.

"Schematics"

Wires connected to the ESP8266 module

Wires connected to the MAX7219-based display

Both modules are highly-integrated, and therefore very few connections are required. The connections are as follows:

Note that my prototype uses relatively long wires between the two modules: for a more compact result, much shorter wires could be used, or even near-direct soldering of pins.

The prototype also uses non-contiguous pins D1, D2, and D4, perhaps because some documentation somewhere convinced me not to use D3 on my first attempt. I'm 80% certain that there is no good reason to avoid that pin and I should test that theory someday.

Software

The high-level view is that the ESP module exposes a UDP server, listening for a simple home-brewed language of instructions on port 4444, and translates them to MAX7219 instructions, so that their effects can be seen on the LED displays:

• 0x01: initialize displays;
• 0x02: clear displays;
• 0x03: refresh displays (i.e., commit the in-ESP buffer to displays, but other commands auto-commit when relevant);
• 0x80: write text, the next bytes are character values to print on the display;
• 0x81: set font at character, the next byte is the character index, and the next n bytes, where n is the display's line count, are the pixels making up the character.

Code walk-through

Arduino sketch source code: esp8266-max7219-relay.ino.

The preamble defines constants for easy reference to pins and dimensions, sets up an object of type WiFiUDP, a static buffer for incoming UDP packets, and two buffers representing the current and upcoming states of the display. A static font array is defined, holding a byte for each supported character's line (in the prototype, only digits 0-9, colon and space are supported).

The standard Arduino setup function initializes output pins, initializes the display, starts the Wi-Fi connection (blinking some of the display while connection is being established), and then starts the UDP server.

void setup() {
    Serial.begin(115200);

    pinMode(outData,   OUTPUT); // MAX7219 DIN
    pinMode(outClock,  OUTPUT); // MAX7219 CLK
    pinMode(outCommit, OUTPUT); // MAX7219 LOAD / ¬CS

    pinMode(outLed,    OUTPUT);

    display_init();

    WiFi.begin(ssid, pass);
    int i = 0;
    while (WiFi.status() != WL_CONNECTED) {
        Serial.println("Not connected.");
        // Toggle first square.
        for (int l = 0; l < LINES; ++l) {
            scratch[i + l * DISPLAYS] ^= 0xff;
        }
        refresh_display();
        delay(250);
    }
    Serial.println("Connected!");

    Udp.begin(port);
}

The main loop listens for incoming commands and dispatches them to onReceive, which is recycled from the previous project, as is all of the MAX7219-specific code. (That code is a straightforward implementation of the language described in the chip's spec sheet.)

void loop() {
    if (Udp.parsePacket() == 0) return;
    int count = Udp.read(buf, sizeof buf);
    Serial.printf("Received %d bytes; [0] = 0x%02x.\r\n",
                  count, buf[0]);
    onReceive(count);
}

static void onReceive(int bytes) {
    if (bytes < 1) return;

    byte instr = buf[0];
    --bytes;

    switch (instr) {
    case 0x01: display_init(); break;     // Init
    case 0x02: memset(scratch, 0, BYTES); // Clear
    case 0x03: refresh_display(); break;  // Commit

    case 0x80: {                // Write (text)
        if (bytes < CHARACTERS) return;

        memset(scratch, 0, BYTES);
        for (int i = 0; i < CHARACTERS; ++i) {
            byte *c = fontAt(buf[i + 1]);
            compositeDigit(c, i);
        }
        refresh_display();

        break;
    }

    case 0x81: {                // Set font
        if (bytes < LINES + 1) return;
        byte c = buf[1];             // Character to write
        byte *fontPoint = fontAt(c); // Never fails

        for (int i = 0; i < LINES; ++i) {
            fontPoint[i] = buf[i + 2];
        }
        break;
    }
    }
}

Simple code to push the current time to the ESP/MAX display

This is as simple as writing the time in HH:MM:SS format, preceded by the 0x80 instruction byte, through UDP to port 4444 on the correct host, several times a second for freshness. Assuming your ESP8266's hostname is esp0, the following Bash code will do:

while true; do
  date $'+\x80%T' >/dev/udp/esp0/4444
  sleep 0.1
done

%T is a Posix date equivalent for %H:%M:%S. Users of GNU date may prefer %_H:%M:%S, which prints the hour space-padded instead of zero-padded.

Future work

Possible improvements:

• Allow transmitting a raw bitmap to display instead of limiting to digits, perhaps include a scrolling capability;

• for the text format: allow at least all alphanumeric characters, for non-clock applications;

• build some resilience into the clock:

  • at the very least, mention on the display that Wi-Fi connectivity has been lost (e.g., by blinking a pixel), as this will help differentiate between a crashed controller (ESP8266, MAX7219, or in-between) and loss of network;

  • consider switching to a more abstract format for on-wire transmission of the current time, letting the module increment time using its internal timer while the more precise feed is unavailable, probably mentioning that condition on the display as well.

References

• Maxim MAX7219 / MAX7221 datasheet (PDF);
• Wemos D1 mini.

www.kurokatta.org

David Haguenauer <www@kurokatta.org>
$Id: esp8266-max7129-led-clock.malblog,v 1.14 2020/12/21 00:58:16 homer Exp $