Hardware C/C++

There's never been a better time to play with an interesting piece of hardware. There's a wide variety of cheap and capable devices about, and with AI coding this no longer needs to be something that sits in a drawer gathering dust until you find some time one weekend to dig through tutorials trying to get some pixels on the screen.

Here I take an ESP32 development board with a 1.75 inch round screen, battery power and a fully enclosed case, and turn it into a clock. The clock is running at the top of this page in an emulator.

The device

The board is Waveshare's ESP32-S3-Touch-AMOLED-1.75C: a round 1.75 inch AMOLED on an ESP32-S3, small enough to sit in the palm of your hand. It is one of the few devices of this form factor that comes complete with an attractive machined aluminium case and a battery, so it does not need to be connected to run.

The device, running the wooden clock face
The device, running the wooden clock face
SpecDetail
BoardWaveshare ESP32-S3-Touch-AMOLED-1.75C (SKU 33691)
ProcessorESP32-S3, dual-core Xtensa LX7, up to 240MHz
Wireless2.4GHz Wi-Fi, Bluetooth 5 LE
Display1.75 inch round AMOLED, 466x466, CO5300 driver over QSPI
TouchCST9217 capacitive, over I2C
Memory8MB octal PSRAM, 32MB flash
SensorsQMI8658 6-axis accelerometer and gyroscope
AudioES8311 and ES7210 codec, speaker and microphones
PowerAXP2101 power management, USB-C, 3.7V lithium battery
CaseCNC aluminium, with BOOT and PWR buttons and a lanyard
The board's specifications

Setup

I installed the battery, screwed the back of the case on and plugged the board in over USB-C.

Before changing anything on it I wanted a way back. I asked Claude Code to examine the device and pull a copy of its existing flash storage, so that I could restore it to the factory image later if I needed to. It worked out the layout, talked to the board over its serial bootloader and pulled the whole 32MB image off it.

A first clock

The board sat plugged in on my desk while I worked, so I could look at it as well as read the code. I went straight in and asked Claude to make a clock: a wooden background, a chrome edge, and numbers around the face. With a small amount of tweaking I had a fairly good clock.

The first clock face, with a wooden background and chrome edge
The first clock

Most of the requests were just layout changes: adding the ticks around the edge of the face and positioning the numbers the way I wanted.

After that I asked it to make a set of clock faces that you could switch between by pressing on the screen, and in no time I had a set of different faces without even having said what each one should be. I threw away the ones I didn't like and kept seven, again with some visual tweaks and a bit of customisation. There's a wooden one, a Casio-style digital, a neon ring, a plain Bauhaus face, a red LED display, a little solar system, and a glowing green vector face.

Wooden clock face
Wood
Casio-style digital clock face
Casio
Neon ring clock face
Neon
Bauhaus clock face
Bauhaus
Red LED display clock face
LED
Solar-system clock face
Orbit
Glowing green vector clock face
Vector
The seven clock faces

Performance

The CPU isn't quite fast enough to send a whole frame to the screen 60 times a second for smooth animation, and some of the face backgrounds also took a noticeable moment to draw when you switched to them.

The screen itself has its own memory which it refreshes from and to draw to it you set a rectangle of pixels on the panel, streaming the pixels over a fast serial bus. On this board the panel is a CO5300 driven over QSPI and you send commands to set the column and row ranges then a pixel command followed by the actual pixel data. The pixels are two bytes each, in RGB565 and the cost is roughly proportional to the number of pixels you send. The round face is 466 by 466, which at two bytes per pixel is about 420KB for the whole screen.

As pushing a whole image per frame was not possible the fix was to divide the screen into a grid of 16-pixel squares, a 30 by 30 grid and keep track of which squares are dirty, sending only those which have changed to the panel. For the second hand sweeping round, only the few squares it passes through change each frame so that's all that gets sent and after this change the hand moves smoothly. Each square is sent individually to the panel - it turned out not to be necessary to merge adjacent squares into larger rectangular areas to send in a single request.

The dirty squares, drawn inverted so you can see what is being sent to the panel
The dirty squares, inverted so you can see what's being sent each frame

For switching faces, the backgrounds are rendered once when the program starts and kept in buffers in PSRAM. All seven fit, so switching to a face is just a copy, and then only the hands and digits are drawn on top every frame.

Structure of the code

The program is an ESP-IDF app in C and C++. After it brings up the display, the touch and the power button, it sits in a loop: work out the time, compose the next frame, send the squares that changed, then wait for the next frame.

Composing a frame draws into a plain RGB888 buffer and, as it draws, marks every 16-pixel square it touches as dirty. A small drawing library does the lines, circles, text and the antialiasing; it's all software, drawing into the buffer a pixel at a time.

Sending the frame walks the dirty squares and sends each one. The dirty flags for each row of squares are held as bits in a 32-bit word, so finding the next one is a count-trailing-zeros:

static void send_rect(esp_lcd_panel_handle_t panel, const uint8_t *rgb,
                      uint16_t *scratch, int x0, int y0, int x1, int y1)
{
    hud_pack_rect(rgb, scratch, x0, y0, x1, y1);          //  RGB888 -> RGB565
    esp_lcd_panel_draw_bitmap(panel, x0, y0, x1, y1, scratch);
}

for (int ty = 0; ty < HUD_TY; ty++) {
    uint32_t bits = dirty[ty];
    while (bits) {
        int tx = __builtin_ctz(bits);    //  next dirty square in this row
        bits &= bits - 1u;               //  clear it
        int x0, y0, x1, y1;
        hud_tile_rect(tx, ty, &x0, &y0, &x1, &y1);
        send_rect(panel, rgb, scratch, x0, y0, x1, y1);
    }
}
Sending only the dirty squares (trimmed)

The pixels have to be packed from the buffer's RGB888 into the RGB565 the panel wants, and the CO5300 over QSPI wants the two bytes of each pixel swapped, so the packer does both at once:

static uint16_t pack565(uint8_t r, uint8_t g, uint8_t b)
{
    uint8_t r5 = r >> 3;
    uint8_t g6 = g >> 2;
    uint8_t b5 = b >> 3;
    uint16_t c = (r5 << 11) | (g6 << 5) | b5;
    return (c << 8) | (c >> 8);   //  CO5300 over QSPI wants the bytes swapped
}
Packing a pixel into byte-swapped RGB565

The faces that are expensive to draw are pre-rendered once into one slab of PSRAM, one background per face, so a switch is a copy rather than a redraw:

//  All face backgrounds are drawn once at startup into one PSRAM slab,
//  so switching to a face is a copy, not a redraw.
uint8_t *slab = heap_caps_malloc(k_fb * CLOCK_FACES, MALLOC_CAP_SPIRAM);
for (int i = 0; i < CLOCK_FACES; i++) {
    s_static[i] = slab + k_fb * i;
    draw_static_face(s_static[i], i);
}
Pre-rendering the face backgrounds (trimmed)

The clock at the top of the page is this same program — and not just the drawing code recompiled, but the actual firmware binary you would flash to the board, booted in an emulator of the whole board that is itself compiled to WebAssembly. The clock code and its dirty-square logic run completely unchanged on the emulated chip, and the pixels reach the screen over the emulated QSPI bus exactly as they do on the device. It starts at the ROM reset vector and runs the bootloader and the app — a few seconds to boot — then runs live; tap the face to change it.

Source code

The whole clock application: the exact source compiled both for the board and, unchanged bar the panel, for the clock at the top of this page.

The application

  • clock.c C · 1678 lines · the seven faces, drawing and the frame loop
  • clock.h C · 29 lines · the clock's public interface
  • hud.c C · 1213 lines · the software drawing library and dirty-square packer
  • hud.h C · 105 lines · the drawing library interface and dirty-tile geometry

Bringing up the board

  • main.cpp C++ · 377 lines · brings up the display, touch and power, then runs the clock
  • CMakeLists.txt CMake · 15 lines · the ESP-IDF component build

See also