This is an emulator for the Waveshare ESP32-S3-Touch-AMOLED-1.75C, written from scratch in C, which can run the board's real firmware binaries unchanged. The image you would flash to the device boots from the chip's reset vector through the bootloader and an HTML canvas takes the place of the screen. I made this so I could embed the clock and other programs for the board into this website.
The board is a small round AMOLED on an ESP32-S3 in an aluminium case. The display panel has its own memory, and the chip talks to it using a protocol which you use to specify a rectangle and then send the pixel data via DMA. It is not fast enough to drive 60 frames per second with full-screen refresh (from some basic experiments you can update about half the screen if you want full frame rate).
The hardware specifications:
| Part | Detail |
|---|---|
| Chip | ESP32-S3, dual-core Xtensa LX7, up to 240MHz |
| Memory | 8MB octal PSRAM, 32MB NOR flash, ~512KB internal SRAM |
| Display | 1.75 inch round AMOLED, 466x466, CO5300 driver over QSPI |
| Touch | CST9217 capacitive, over I2C |
| Power | AXP2101 power management, over I2C |
I built this emulator using Claude Code, and took two parallel approaches: writing the whole thing from scratch and using the Espressif fork of QEMU. Both are worth it, and they end up in different places. The from-scratch one is below; the QEMU comparison is at the end.
Running it here
The emulator is running at the top of the page. The whole interpreter core including the CPU, the memory map, the peripherals and the CO5300 model described below is compiled to WebAssembly and runs in the browser. It's running a small test program of a few hundred bytes, a bare-metal self-test that loads straight into SRAM and starts instantly.
The self-test prints the device details over the emulated UART, and the flash size it reports is not a constant; it asks the modelled flash chip for its JEDEC id over the SPI command engine and works out the capacity from the answer. Then it paints a colour-bar test pattern onto the panel by building GDMA descriptors and driving the SPI2 bus exactly as the display driver does, so the pixels travel the same path through the chip that the clock's pixels do. The small print at the end of this article shows that self-test in full, alongside the whole emulator.
The CPU
The ESP32-S3 has two Xtensa LX7 cores. The emulator is an interpreter: it reads the instruction at the program counter, does what it says, moves on. There's no recompilation, which keeps it simple and easy to reason about; it's slower than the real chip, but fast enough to boot and run.
The unusual thing about Xtensa for anyone coming from ARM or x86 is the register window. The code sees sixteen registers, a0 to a15, but the chip has sixty-four physical ones, and a call slides the window along by 4, 8 or 12 registers rather than pushing to a stack. a0 holds the return address and a1 is the stack pointer. When the window wraps all the way round, the oldest registers are spilled to the stack by an exception, so the interpreter has to implement the window exceptions as well as the instructions:
| Register | What it's for |
|---|---|
| a0–a15 | The sixteen general registers the current window sees (a0 return address, a1 stack pointer) |
| AR[0–63] | The sixty-four physical address registers the window slides over |
| PC | Program counter |
| PS | Processor state: interrupt level, window overflow enable, the call increment |
| WindowBase, WindowStart | Where the current window sits, and which windows hold live frames |
| SAR | Shift amount, for the shift and funnel-shift instructions |
| LBEG, LEND, LCOUNT | Zero-overhead loops: hardware jumps from LEND back to LBEG LCOUNT times |
| EPC1–7, EPS2–7, EXCSAVE1–7 | Saved PC, state and scratch per interrupt level, on an exception |
| EXCCAUSE, EXCVADDR | Why the last exception fired, and the address that caused it |
| INTENABLE, VECBASE | Which interrupts are enabled, and the base of the exception vectors |
Both cores run from the same memory and peripherals. The emulator steps core 0, then core 1, one instruction each, and the second core is only brought online when the first releases it, which is what the real startup does. The system timer that drives the FreeRTOS tick is advanced on each step and raises its interrupt through the interrupt matrix, so the scheduler runs and tasks switch exactly as on the chip.
Storage
The 32MB flash holds everything: the bootloader, the partition table, the app, and the read-only data and media above it. Most of the time the firmware reads flash through the address space, because the MMU maps it into the instruction and data windows and the cache fetches from it. The emulator serves those reads straight from a 32MB buffer, translating the address through the same MMU table the bootloader programmed.
But flash is also a SPI chip with a command protocol, and the firmware talks to it directly when it needs to erase or program, or when it's identifying the chip at boot. That goes through a dedicated command engine in the memory controller: the firmware writes a command and address into registers, sets a trigger bit, and polls it until the hardware clears it. The emulator honours that contract, decoding the flash commands (read, write, erase, and the JEDEC id) and running them against the buffer. The id matters more than it sounds: the chip reports a capacity byte, and if the emulator claims 16MB while the image header says 32MB, the startup aborts before it ever reaches the app. The emulated chip reports 32MB, so the probe passes and the board boots.
Memory and boot
The backing memory is placed at the real ESP32-S3 addresses, so the unchanged image loads and runs where it expects to. Internal SRAM is one block seen through several windows: the same bytes appear on the data bus at 0x3FC88000 and on the instruction bus at 0x40378000, which the startup code relies on when it copies code in through one and runs it through the other. Flash and PSRAM aren't in the address space directly; they're mapped in 64KB pages by an MMU table the bootloader fills in, flash for instructions at 0x42000000 and for read-only data at 0x3C000000.
| Address | Region |
|---|---|
| 0x3C000000 | Flash, read-only data, mapped by the MMU |
| 0x3FC88000 | Internal SRAM (data bus) |
| 0x40000000 | Mask boot ROM code |
| 0x40378000 | Internal SRAM (instruction bus, the same bytes) |
| 0x42000000 | Flash, instructions, mapped by the MMU |
| 0x50000000 | RTC fast RAM |
| 0x600C5000 | The flash/PSRAM MMU page table |
| 0x60000000 | Peripheral registers (1MB window) |
Boot is faithful: the whole 32MB flash image is loaded, and the CPU starts at the ROM reset vector, 0x40000400, exactly where the chip starts on power-up. To make that work, the emulator loads the real ESP32-S3 mask ROM, so the chip's own first-stage loader runs, reads the second-stage bootloader from flash, which sets up the clocks and the MMU and loads the app's segments, and then jumps into the app. Nothing is shortcut: the boot log that comes out of the emulated UART is the board's own boot log, down to the SPI mode and the partition table.
The screen
On the device nothing ever writes a pixel to a memory address. The panel is a CO5300 with its own frame memory, and the only way to change the screen is to send it messages over a four-wire QSPI bus: you set a rectangular window, stream pixels into it, and the panel shows whatever is in its memory. There is no framebuffer in the ESP32-S3 to poke.
At the lowest level the chip does not send those messages from a register either. The SPI2 peripheral transmits whatever a GDMA channel points at, so to send one message you put the bytes somewhere in RAM, describe them in a DMA descriptor, write that descriptor's address into the channel's OUT_LINK register, and set the transaction's start bit. The controller clocks the bytes out over the four data lines and raises a done flag. The clock application reaches all of this through ESP-IDF's esp_lcd driver, but you do not have to; the hardware contract is just “point DMA at some bytes and press go”:
// One message is one SPI2 transaction, and SPI2 sends whatever GDMA points
// at - so you describe the bytes in a descriptor and set the start bit.
static void send(const uint8_t *bytes, uint32_t len)
{
memcpy(dma_buf, bytes, len);
desc[0] = (len << 12) | DMA_SUC_EOF | DMA_OWNER; // length + "last" + owner
desc[1] = (uint32_t) dma_buf; // the bytes to send
desc[2] = 0; // no next descriptor
REG(GDMA_OUT_LINK_CH0) = (uint32_t) desc & 0xFFFFF;
REG(SPI2_CMD) = SPI_USR; // press go
}
// A command header is always {opcode, 0x00, command, 0x00}.
static void header(uint8_t opcode, uint8_t cmd)
{
uint8_t h[4] = { opcode, 0x00, cmd, 0x00 };
send(h, sizeof h);
}Every message starts with that four-byte header, {opcode, 0x00, command, 0x00}: the first byte is the QSPI write opcode and the third is the panel command. Any parameters or pixels come after it, as their own message. Only two opcodes matter — 0x02 writes a command and its parameters, and 0x32 writes pixel data (the one case that drives all four data lines at once) — and with those the command set the display actually needs is short:
| Message | Opcode | Command | Payload that follows |
|---|---|---|---|
| Set column window | 0x02 | 0x2A (CASET) | x-start then x-end, each a big-endian 16-bit value, inclusive (4 bytes) |
| Set row window | 0x02 | 0x2B (RASET) | y-start then y-end, the same way (4 bytes) |
| Write pixels | 0x32 | 0x2C (RAMWR) | RGB565 pixels, two bytes each (byte-swapped), filling the window left to right, top to bottom |
| Set up the panel | 0x02 | 0x11 sleep-out, 0x29 display-on, 0x36 MADCTL, 0x3A COLMOD, 0x51 brightness, … | zero or a few parameter bytes; configures the panel but changes no pixels |
Everything the screen does is built from those. Here is a complete rectangle fill written directly against the hardware, with no driver in the way:
// Fill the rectangle (x0,y0)..(x1,y1), inclusive, with one RGB565 colour.
void fill_rect(int x0, int y0, int x1, int y1, uint16_t colour)
{
header(0x02, 0x2A); // CASET: the column range
uint8_t cols[4] = { x0 >> 8, x0, x1 >> 8, x1 };
send(cols, 4);
header(0x02, 0x2B); // RASET: the row range
uint8_t rows[4] = { y0 >> 8, y0, y1 >> 8, y1 };
send(rows, 4);
header(0x32, 0x2C); // RAMWR: pixels follow
int n = (x1 - x0 + 1) * (y1 - y0 + 1);
for (int i = 0; i < n; i++) { // RGB565, two bytes, big-endian
pixels[i * 2] = colour >> 8;
pixels[i * 2 + 1] = colour;
}
send(pixels, n * 2); // stream them into the window
}The emulator sits at the far end of that bus. When the firmware sets the start bit, it gathers the DMA bytes for the transaction and hands them to a model of the CO5300, which tracks the current window and a write cursor and drops RAMWR pixels into a 466x466 frame buffer — the panel's memory. Decoding a message is the mirror image of sending one:
void co5300_spi2_xfer(const uint8_t *data, uint32_t len)
{
// A four-byte transfer starting with a QSPI opcode is a command header.
if (len == 4 && (data[0] == 0x02 || data[0] == 0x32)) {
s_cmd = data[2]; // {opcode, 0x00, cmd, 0x00}
if (data[0] == 0x32 && s_cmd == 0x2C) begin_ramwr(); // pixels follow
return;
}
switch (s_cmd) {
case 0x2A: s_x0 = (data[0] << 8) | data[1]; // CASET: column window
s_x1 = (data[2] << 8) | data[3]; break;
case 0x2B: s_y0 = (data[0] << 8) | data[1]; // RASET: row window
s_y1 = (data[2] << 8) | data[3]; break;
case 0x2C: // RAMWR: RGB565 pixels
for (uint32_t i = 0; i + 1 < len; i += 2) {
s_fb[s_cur_y * CO5300_W + s_cur_x] = data[i] | (data[i + 1] << 8);
if (++s_cur_x > s_x1) { s_cur_x = s_x0; s_cur_y++; }
}
break;
}
}Pixels on this panel are RGB565 with the two bytes swapped, which is how the firmware packs them, so the model stores them as it receives them and swaps back only when it reads the frame memory out to the canvas. Because the data path is the real one, the dirty-square trick the clock uses falls out for free: the emulator sees exactly the small windows the clock sends, nothing more. Here's the clock running under it, booted from the real binary:
The QEMU route
The other run used the Espressif fork of QEMU, which has a machine for the ESP32-S3. It's a different kind of effort: instead of writing the chip, you configure a machine that already exists and see how far the firmware gets. It gets a long way. With the octal PSRAM option turned on and a 32MB flash model, the same binary boots through the bootloader, the PSRAM is detected and speed-tested, and it reaches the app:
I (142) esp_psram: Found 8MB PSRAM device
I (156) app_init: Project name: wood_clock
I (170) main_task: Calling app_main()
I (179) co5300: version: 2.2.0
I (180) co5300_spi: LCD panel create success, version: 2.2.0And then it stops. That last line is the panel driver creating its object; the next thing it does is send the panel its first command, and the ESP32-S3 machine in QEMU has no model for the CO5300, or for the QSPI display path, or for the I2C touch and power chips. So the first panel transaction never completes and the clock loop is never reached. There's no picture.
That's the difference between the two, and it's the whole point of doing both. QEMU is excellent for what it models: it proved the binary was built correctly, flashable at the right offsets, and that the chip, the PSRAM and the partitioning were all right, with none of the work of writing a CPU. The from-scratch emulator is more work, but because it models the display path it can actually show the clock, which is the thing I wanted to see. For this board, if you want pixels, you have to write the panel.
Source code
The whole emulator, in C, plus the small self-test that runs in the hero at the top of the page.
The self-test (runs in the hero)
- wtest.c C · 115 lines · prints the device details and paints the panel over QSPI
- start.S Assembly · 19 lines · the entry stub: disable window exceptions, set a stack, call main
- wtest.ld Linker script · 17 lines · links the whole self-test into one SRAM block
The emulator core
- xtensa.c C · 932 lines · the Xtensa LX7 interpreter
- xtensa.h C · 57 lines · the CPU state
- mmio.c C · 648 lines · the peripheral registers: UART, SPI flash, PSRAM, SPI2/GDMA, I2C, timers
- mem.c C · 138 lines · the memory map and the flash/PSRAM MMU
- mem.h C · 35 lines · the memory interface
- co5300.c C · 88 lines · the CO5300 QSPI command decoder and frame memory
- co5300.h C · 15 lines · the panel interface
- image.c C · 79 lines · loads the flash image and app segments
- elf.c C · 59 lines · the ELF loader (the mask ROM and the self-test)
- panel.c C · 40 lines · the LCD_CAM panel model (shared plumbing)
- panel.h C · 13 lines · the panel interface
- sdcard.c C · 270 lines · the SPI SD-card model (from the Paper-S3 lineage)
- sdcard.h C · 13 lines · the SD-card interface
- main.c C · 150 lines · the desktop front-end: boots the real firmware, steps both cores
- wasm.c C · 71 lines · the browser front-end: runs the self-test, reads out the panel
- Makefile Makefile · 40 lines · the desktop and WebAssembly build
See also
- A clock on a round ESP32 display - The clock this emulator runs, built on the board and compiled to run in the browser
- Real-time ray tracing on a round ESP32 display - A real-time ray tracer for the same board, kept interactive by refining only the pixels that matter