Hardware
The firmware is an ESP-IDF application (firmware/esp32) built on the portable core. The reference board uses common modules you can wire on a breadboard. Other boards need a configuration and, where necessary, drivers; see porting.md.
Start with Supported hardware for a board comparison, then check capabilities and verification. The release builds are experimental until a physical report is recorded for the exact model and revision.
Requirements
- Chip: the release profiles target ESP32-S3. Other ESP32 variants need their own configuration and validation. On a board without PSRAM, either the whole-panel framebuffer (width × height × 2 bytes) fits in internal RAM next to Wi-Fi and audio buffers, or the board holds a band of rows and lets the UI render in bands (see
Display::framebuffer_rows()and the CYD below). - Display: an SPI ST7789 panel (240×320, 240×240 or 240×135). Other controllers need a different
esp_lcdpanel driver. - Microphone: an I2S MEMS microphone (INMP441, ICS-43434, SPH0645 style).
- Speaker (optional): an I2S class-D amplifier (MAX98357A) and a 4–8 Ω speaker.
- Buttons: at least one (TALK). The DevKit's BOOT button works; a second button for CANCEL is recommended.
Back up the factory firmware
Most board sections below give an esptool.py ... read_flash line that saves the board's factory firmware before its first flash. PlatformIO's own esptool is not on the shell path, so with PlatformIO as the only install, run the line through it with the same arguments:
pio pkg exec -p tool-esptoolpy -- esptool.py --chip esp32s3 read_flash 0 0x1000000 my-board-factory.bin
Or install esptool with pip install esptool and run the lines as written. esptool 5 warns that esptool.py and read_flash are older names, and runs them. The Cardputer ADV line is written for esptool 5 (esptool ... read-flash); through PlatformIO's esptool 4, write it as pio pkg exec -p tool-esptoolpy -- esptool.py --chip esp32s3 --port /dev/ttyACM0 read_flash 0 ALL original-cardputer-adv.bin.
The default speed is slow: on an ES3C28P's USB port a 16 MB read took 24 minutes. Adding -b 921600 before read_flash made it about seven times faster.
Before flashing, check that a full-flash backup has the board's full flash size: 16,777,216 bytes for 0x1000000 (16 MB), 8,388,608 bytes for 0x800000 (8 MB), and for ALL the size esptool reports for the detected flash. ls -l shows it. A shorter file is not a backup; read the flash again. A line that reads one partition instead (the AIPI Lite's read_flash 0x9000 16384) gives a file of exactly that length.
Keep backups private. A factory image can hold the vendor's service credentials (the AIPI Lite's does), and an image read after setup holds your Wi-Fi password and the device's key. Save them in a folder only you can read, and don't commit, upload or share them.
ESP32-S3 breadboard
Board option esp32s3-breadboard, for an ESP32-S3-DevKitC-1 N8R8 and the modules above.
- Flash: 4 MB or more. The same image runs on 4, 8 and 16 MB modules.
- PSRAM: octal, as on the N8R8 and N16R8. On an N8R2 (quad PSRAM) or a module without PSRAM, the firmware still starts and says so in its log, but the display may not: the framebuffer needs PSRAM. For an N8R2, build with
CONFIG_SPIRAM_MODE_QUAD=yinstead.
| Module | Signal | ESP32-S3 GPIO |
|---|---|---|
| ST7789 LCD | MOSI / SDA | 11 |
| SCLK / SCL | 12 | |
| CS | 10 | |
| DC | 9 | |
| RST | 8 | |
| BL (backlight) | 7 | |
| VCC / GND | 3V3 / GND | |
| INMP441 mic | SCK | 4 |
| WS | 5 | |
| SD | 6 | |
| L/R | GND (left channel) | |
| VDD / GND | 3V3 / GND | |
| MAX98357A amp | BCLK | 15 |
| LRC | 16 | |
| DIN | 17 | |
| VIN / GND | 5V / GND | |
| Buttons (to GND) | TALK | 0 (BOOT) |
| CANCEL | 14 |
All pins avoid the S3's flash/PSRAM pins (26–37) and native USB (19/20). Use Custom pins in menuconfig to change any of them.
Waveshare ESP32-S3-LCD-1.54
Board option esp32s3-lcd-154, for Waveshare's all-in-one 1.54" board (SKUs 33866/33867; the -EN SKU is the same hardware): an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a 240×240 ST7789 panel over SPI, an ES8311 DAC and an ES7210 microphone ADC with two microphones, an NS4150B amplifier, a speaker, a QMI8658 6-axis IMU, a TF card slot, a battery charger and the BOOT / PLUS / PWR keys. Nothing to wire and nothing to connect, it works out of the box. The touch version (ESP32-S3-Touch-LCD-1.54, SKUs 33868/33869) adds a CST816 touchscreen, which the same profile drives; on the non-touch SKUs nothing answers at its address and the touchscreen is reported absent.
| Part | Chip | Connection |
|---|---|---|
| Display | ST7789, SPI | SCLK 38, MOSI 39, CS 21, DC 45, RST 40, BL 46 (LEDC) |
| Speaker DAC | ES8311 | I2C 0x18; I2S MCLK 8, BCLK 9, WS 10, DOUT 12; amplifier enable 7 |
| Microphones | ES7210 | I2C 0x40; I2S DIN 11 (shares the bus above), MIC1 + MIC2 |
| Touch (touch version) | CST816 | I2C 0x15 on the bus below; RST 47 |
| IMU | QMI8658 | I2C 0x6B |
| I2C bus | SDA 42, SCL 41, 400 kHz | |
| Buttons (to GND) | TALK = BOOT (0), CANCEL = PLUS (4), power key = PWR (5) | |
| Battery | ETA6098 | GPIO 1 (BAT_ADC), GPIO 2 (power latch), GPIO 3 (CHG_STAT) |
The PWR key is part of the power circuit and also reads low on GPIO 5 while pressed (latch_power.key). A short press turns the screen off and on; holding it for 2.5 seconds lowers GPIO 2, which powers the board off on battery. Firmware asserts GPIO 2 at startup to keep the battery path enabled. On the touch version, holding the screen talks and a swipe down cancels, as on other touch boards. The TF card and QMI8658 are unused.
The device settings menu shows calibrated battery-node voltage and the charging signal. GPIO 1 samples the R27/R32 divider, whose ratio is three. GPIO 3 reads the active-low charging signal. This board has no fuel gauge, battery presence detector or USB-status input, so those readings are omitted. External power is reported while CHG_STAT reads charging or a USB host is connected to the USB-C port (latch_power.usb_external_power), and battery otherwise, so Wi-Fi modem sleep applies on battery; a USB charger without data that has finished charging counts as battery. Voltage is unavailable if the ESP32's ADC calibration cannot start. An unplugged battery can leave voltage on this node while USB powers the charger; voltage alone does not prove a battery is attached.
After confirming a compatible single-cell 3.7 V Li-ion battery is fitted, opt into a rough display-only percentage with set battery_estimate liion, then set battery_display percentage. See battery indicator settings and limitations. It is off by default, stays visible while charging, and does not change raw gateway telemetry or establish charge completion. Do not enable it merely because this node has voltage; USB can energize the node without a battery. Simulator checks and firmware compilation do not calibrate or physically verify this estimate.
Select Power off twice to lower GPIO 2 and disconnect battery power. USB continues to power the board. Disconnect USB to turn it off, and hold PWR to turn it back on from battery. Holding PWR for 2.5 seconds while the board runs does the same as Power off; on USB the screen goes dark instead. BOOT and PLUS retain their TALK and CANCEL roles. The optional screen timeout dims and darkens the display while keeping Wi-Fi connected.
While the screen is dark, on battery and idle, the chip dozes: the CPU drops to 80 MHz when idle at any time, and while dozing it takes light sleep between Wi-Fi beacons, waking every 100 ms to read the keys and, on the touch version, the touchscreen. The battery latch, the panel's control lines and the amplifier enable keep their level through light sleep. Light sleep never runs while a USB host is connected (the console and JTAG would stop), so a doze shows only on battery.
Wiring follows the Waveshare schematic. For physical verification, compare the displayed voltage with a meter, test with and without a battery, check the charging signal, and test shutdown separately with USB and battery power. Record the board revision in the hardware checklist.
Build and flash it with PlatformIO (pio run -e esp32s3-lcd-154 -t upload -t monitor) or with idf.py:
cd firmware/esp32
idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/waveshare-esp32s3-lcd-154/sdkconfig.defaults" build
idf.py -p /dev/cu.usbmodem101 flash monitor
The USB-C port is the S3's own USB Serial/JTAG, so flashing and the serial console (115200 baud) both use it, exactly like the AMOLED board.
First flash: what to check
- Boot log:
ST7789 240x240 ready,codecs: speaker ready, microphones ready, and inhermes-gadget diagani2clist with0x18(ES8311) and0x40(ES7210).0x6b(QMI8658) answers too. - Screen: the mascot is centred, upright and not mirrored, and the colours are right (amber accents, not blue). If the image is mirrored, flip
mirror_x; a one-pixel stripe at an edge means the gap is off. The panel is written for SPI mode 0; Waveshare's own demo uses mode 3, so a blank or garbled screen is a candidate for changingio_cfg.spi_modeinport_display.cpp. - Microphone: say something while holding BOOT; the waves move with your voice and Hermes's transcript is right. The ES7210 is configured here the same way as the AMOLED board (I2S standard mode, MIC1 + MIC2). If the capture is silent or wrong, Waveshare's factory demo drives the ADC in I2S TDM mode (4 slots,
bclk_div8) instead, which is the first thing to try. - Speaker: replies are clear and loud enough (
set volume 80); no hiss between replies. - Buttons: BOOT holds to talk, PLUS cancels, and holding PLUS for 2 s starts a new conversation.
Waveshare ESP32-S3-Touch-LCD-1.83
Board option waveshare-touch-lcd-183, for the Waveshare ESP32-S3-Touch-LCD-1.83 (SKUs 32790 and 32791; the -EN SKU is the same hardware): an ESP32-S3R8 with 16 MB flash and 8 MB octal PSRAM, a 1.83" 240×284 ST7789P panel over SPI, a CST816D touchscreen, an ES8311 speaker codec, an ES7210 microphone ADC, an AXP2101 power manager, a QMI8658 IMU, a PCF85063 RTC and a TF card slot. This port is experimental. It has not been run on a board.
Back up the whole flash before the first flash. The board has no other copy of its factory firmware:
esptool.py --chip esp32s3 read_flash 0 0x1000000 touch-lcd-183-factory.bin
Writing that file back at 0x0 restores the original firmware.
| Part | Chip | Connection |
|---|---|---|
| Display | ST7789P, SPI | MOSI 7, SCLK 6, CS 5, DC 4, RST 38; 24 MHz, SPI mode 0; colors inverted; offsets 0; backlight GPIO 40, active high |
| Speaker DAC | ES8311 | I2C 0x18 on SDA 15, SCL 14; I2S MCLK 16, BCLK 9, WS 45, DOUT 8, DIN 10; amplifier enable 46 |
| Microphone ADC | ES7210 | I2C 0x40 on the same bus; MIC1 and MIC2, standard I2S. The echo-reference channel is not used |
| Touch | CST816D | I2C 0x15 on the same bus; RST 39, INT 13 (the driver polls) |
| Power | AXP2101 | I2C 0x34. ALDO1 at 3.3 V supplies the microphone. PWR is the PMIC power key |
| Keys | BOOT GPIO 0 (TALK) |
Hold the screen or BOOT to talk, tap to answer yes, and swipe down to cancel. A short press on PWR turns the screen off and on. The profile reads that press from the AXP2101, the same way the 2.06 watch does. One published pin list names GPIO 41 as a power button and never uses it; this profile does not read GPIO 41. If PWR does nothing on a unit, that pin is the first thing to check.
The AXP2101 reports battery voltage, charging and external power. There is no measured discharge curve for this cell, so a percentage is the chip's own gauge or the uncalibrated linear fallback, not a fitted curve. Do not treat it as a state of charge. The QMI8658, the PCF85063 and the TF card are present and unused. Light sleep is off.
The glass is 240×284. To preview that layout, run hermes-gadget sim --board sim-240x284. A stripe along an edge means lcd.gap_x or lcd.gap_y is wrong; both are 0 until a unit says otherwise.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e waveshare-touch-lcd-183 -t upload -t monitor
Or with idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/waveshare-esp32-s3-touch-lcd-1.83/sdkconfig.defaults" build. The USB-C port is the S3's own USB Serial/JTAG, so flashing and the serial console (115200 baud) both use it.
First flash: what to check
- Boot log:
ST7789 240x284 readyandcodecs: speaker ready, microphones ready.hermes-gadget diagshould listdisplay st7789,microphone es7210,speaker es8311, and I2C devices0x18,0x40,0x15and0x34. - Screen: the mascot is upright and not mirrored, and the colors are right (amber accents, not blue). A negative image means
lcd.invertis wrong. A blank panel is a candidate for SPI mode 3. One pin list names mode 3, and the board file that starts this panel sets mode 0, which is what the firmware uses. - Brightness: the settings menu's brightness steps dim the screen, and 100 percent is the brightest. Reversed steps mean
lcd.backlight_invertis wrong. - Touch: holding the screen records, a swipe down cancels, and taps land where you touch.
- Microphone: hold BOOT and speak; the waves move with your voice. Silence with the ES8311 present points at ALDO1, which this profile turns on for the microphone.
- Speaker: replies are clear and loud enough (
set volume 80). - Power:
statusshowsbattery_mv, charging and external power on USB. A percentage, if one appears, is not calibrated. A short PWR press turns the screen off and on.
Pin numbers follow Waveshare's esp32_s3_touch_lcd_1_83 board support package at commit 7945883d. Panel size, color inversion, the 24 MHz clock, touch reset and the AXP2101 microphone rail follow xiaozhi-esp32's waveshare/esp32-s3-touch-lcd-1.83 board at commit 49b4380b (tag v2.5.2). See THIRD_PARTY_NOTICES.
Waveshare ESP32-S3-Touch-LCD-1.85C V2
Use esp32s3-touch-lcd-185c-v2 for the V2 board, PCB Rev2.0: an ESP32-S3R8 with 16 MB flash and 8 MB octal PSRAM, a round 360×360 ST77916 LCD over QSPI, CST816 touch, an ES8311 DAC, an ES7210 microphone ADC with two microphones and an NS4150B amplifier. A V2 board says Rev2.0 on the PCB or has a V2 sticker on the case. V1 has different audio hardware and must not use this image. The standard SKU needs a speaker on the SPK connector; the speaker-box version includes one. This port is experimental; see the partial physical report.
| Part | Connection |
|---|---|
| ST77916 LCD, QSPI | CS 21, clock 40, D0–D3 46/45/42/41, backlight 5 (LEDC); reset through TCA9554 P1 |
| CST816 touch | I2C 0x15, polled; reset through TCA9554 P0 |
| TCA9554 expander | I2C 0x20; the firmware changes only P0 and P1 |
| I2C | SDA 11, SCL 10, 400 kHz |
| ES8311 speaker / ES7210 microphones | I2C 0x18 / 0x40; MCLK 2, BCLK 48, WS 38, DOUT 47, DIN 39; amplifier enable 15 |
| BOOT | GPIO 0, TALK |
Audio. Each I2S frame has two 32-bit slots. The ES7210 packs four 16-bit channels into them: the speaker's playback reference, a microphone, an unused channel and the second microphone. The firmware averages the two microphones into mono and ignores the reference, so there is no echo cancellation. The amplifier is on only while audio plays. Start with a low volume.
Hold the screen or BOOT to talk, tap to answer yes, and swipe down to cancel. RESET is not a CANCEL button. The IMU, RTC, TF card and battery ADC are not used, and the battery switch keeps its hardware function.
cd firmware/esp32
pio run -e esp32s3-touch-lcd-185c-v2 -t upload -t monitor
For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/waveshare-esp32-s3-touch-lcd-1.85c-v2/sdkconfig.defaults" with a separate build directory and sdkconfig. The USB-C port handles flashing and the serial console (115200 baud). The sim-360x360-round simulator board has the same screen.
First flash: what to check
- Boot log:
expander resets 0x03 ready,ST77916 panel ID …,st77916 360x360 ready,codecs: speaker ready, microphones readyandtouch ready. An unknown panel ID leaves the display off. Inhermes-gadget diag, thei2clist has0x15,0x18,0x20and0x40. - Screen: the mascot is centred, upright and not mirrored, the whole circle is visible, and the accents are amber, not blue. Brightness and screen timeout work.
- Touch: holding the centre and each edge starts a recording; a tap answers yes and a swipe down cancels.
- Microphone: the waves move with your voice and Hermes's transcript is right.
- Speaker: replies are clear, with no hiss or pop between them. Cancelling a reply stops it at once, and the next reply plays.
Record the results with the hardware checklist.
References: Waveshare V2 documentation, V2 schematic and the factory demo at 8ead4a96. The demo numbers the expander pins from one (EXIO1 is P0). The LCD initialization tables and their licenses are listed in THIRD_PARTY_NOTICES.
Waveshare ESP32-S3-Touch-LCD-1.46
Use esp32-s3-touch-lcd-146 for the Waveshare ESP32-S3-Touch-LCD-1.46. The same pin table on the wiki covers the 1.46B and the 1.46C. The module is an ESP32-S3R8 with 16 MB flash and 8 MB stacked PSRAM, a round 412×412 SPD2010 LCD over QSPI, SPD2010 touch, an I2S microphone and a PCM5101 speaker. This port is experimental. It was built and not run on a board.
Octal PSRAM at 80 MHz follows the S3R8 pairing used on the other S3R8 boards in this tree. The wiki does not print a flash part order code.
| Part | Connection |
|---|---|
| SPD2010 LCD, QSPI | CS 21, clock 40, D0 to D3 46, 45, 42, 41, backlight 5, active high. Reset is TCA9554 EXIO2. TE on GPIO 18 is unused |
| SPD2010 touch | I2C 0x53, INT GPIO 4, reset TCA9554 EXIO1 |
| TCA9554 expander | I2C 0x20. The firmware pulses bits 0 and 1 and leaves the other bits alone |
| I2C | SDA 11, SCL 10, 400 kHz. The touch device itself runs at 100 kHz |
| Microphone | I2S SCK 15, WS 2, SD 39. MSM261S4030H0R, right slot |
| PCM5101 speaker | BCLK 48, LRCK 38, DIN 47. No MCLK pin and no amplifier-enable pin |
| BOOT | GPIO 0, TALK. The wiki names the button and does not print this GPIO |
Audio. The speaker path is the existing I2S speaker, 16-bit Philips, on I2S0. The microphone is an MSM261S4030H0R on I2S1. The schematic names it U6. Pin 5 (L/R) is net MIC_LRCK_U, and that net is tied to 3V3, so the reader takes the right 32-bit slot. The sample is still 24 bits inside that slot. This has not been heard on a board.
QSPI runs at 20 MHz in SPI mode 3. Espressif's QSPI example macro uses that clock. The factory ESP-IDF header sets mode 0 and 80 MHz, which this driver does not follow. Color order is RGB. Color inversion, axis swap and both mirrors stay off, matching that example. The width 412 is a multiple of 4, which the SPD2010 driver requires. About 282 pixels per inch, from the 412 pixel diameter divided by 1.46 inches. Touch INT is sampled once after the falling-edge handler is installed. The SPD2010 holds that line low until a read sends its CPU-start command and clears INT. A failed read is tried again on the next poll while the line stays low.
Hold the screen or BOOT to talk, tap to answer yes, and swipe down to cancel. The QMI8658, the PCF85063, the TF card, the battery header, the volume knob and the PWR button stay off. The wiki does not give GPIO numbers for the knob, the battery sense or PWR. TF card chip select is EXIO3. RTC interrupt is GPIO 9. IMU interrupts are EXIO4 and EXIO5.
cd firmware/esp32
pio run -e esp32-s3-touch-lcd-146 -t upload -t monitor
For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32-s3-touch-lcd-146/sdkconfig.defaults" with a separate build directory and sdkconfig. The USB-C port handles flashing and the serial console at 115200 baud. There is no simulator profile at 412×412.
First flash: what to check
- Boot log:
expander resets 0x03 ready,spd2010 412x412 ready,microphone ready (i2s),speaker readyandtouch ready. Inhermes-gadget diag, thei2clist includes0x20and0x53. Other chips on the bus may answer too. - Screen: the mascot is centred and upright, the whole circle is visible, and the accents are amber, not blue. Brightness and screen timeout work.
- Touch: holding the centre and each edge starts a recording. A tap answers yes and a swipe down cancels.
- Microphone: the waves move with your voice and Hermes's transcript is right. The right slot comes from the schematic and has not been heard on a board.
- Speaker: replies are clear. Cancelling a reply stops it at once.
Record the results with the hardware checklist.
References: Waveshare documentation, the schematic and the factory demo at fda89ff. The demo repository has no license. Pin numbers come from the wiki. The microphone part and the L/R tie to 3V3 come from the schematic. The expander address, the EXIO bit map and the backlight on-level come from the demo. Display and touch drivers are Espressif components. See THIRD_PARTY_NOTICES.
SenseCAP Watcher W1-A
Use sensecap-watcher for the Seeed Studio SenseCAP Watcher W1-A, hardware
revision v0.2. This is a separate experimental profile, not a Waveshare
profile: the board has an ESP32-S3 with 32 MB flash and 8 MB octal PSRAM, a
round 412×412 SPD2010 display and touch controller, a scroll wheel and button,
an ES8311 speaker codec with an ES7243E microphone ADC (an older ES7243 is used
when that answers instead), and a PCA9535 expander. The camera/HX6538 and
microSD slot are intentionally not exposed.
Hold the screen to talk. The wheel scrolls, and pressing it is CANCEL (holding it 2 s starts a new session); swipe down cancels too. The press that powered the Watcher on is ignored until you let go of the wheel. Power off in the settings menu releases the battery latch; on USB power the board keeps running.
| Part | Connection |
|---|---|
| SPD2010 display (QSPI) | PCLK 7, DATA0 9, DATA1 1, DATA2 14, DATA3 13, CS 45, backlight 8 (active high). No D/C or reset pin |
| SPD2010 touch | I2C1 SDA 39, SCL 38, address 0x53; interrupt on PCA9535 P0.5, read every 20 ms with the wheel button. The controller is read only while it is low: between reports it answers "no points", which would end a held touch |
| General I2C / PCA9535 | SDA 47, SCL 48; expander address 0x21, wheel button P0.3 (active low) |
| PCA9535 supplies | Driven high at boot: P1.1 LCD, P1.2 system (the battery latch), P1.4 codec and amplifier, P1.7 battery divider. Left off: P1.0 microSD, P1.3 Himax AI chip, P1.6 Grove |
| Audio | ES8311 (0x18) speaker; ES7243E (0x14) microphone in the right I2S slot; MCLK 10, BCLK 11, WS 12, microphone DIN 15, speaker DOUT 16 |
| Wheel | GPIO 41 (B) and 42 (A), swapped from the BSP so the scroll goes the way the owner expected; quadrature, a detent every two steps. diag counts its edges and detents under touch.encoder |
| Battery | ADC GPIO 3 through a 62 k/20 k divider (ratio 4, as Seeed's BSP rounds it, so readings are about 2.5% low); voltage is reported, charge state is not |
The pin table is checked against Seeed's SenseCAP Watcher v1.0 schematic, the pinned official BSP and xiaozhi-esp32's Watcher board. The system rail is latched early in boot, before Wi-Fi starts, so on battery you hold the wheel only until the board has started. The camera, Himax flashing UART, and microSD CS/detect remain unsupported.
Factory data
Seeed writes per-device data (the device's identity and keys for SenseCraft) to
an nvsfactory partition at 0x9000, 200 KB long. Nothing can restore it once
it is erased. This profile uses its own partition table,
partitions-sensecap-watcher.csv, which keeps that partition and puts the
firmware after it. pio run -e sensecap-watcher -t upload and the browser installer never write
there. Don't write the release's full image with esptool at 0x0, and don't
run erase_flash: both erase it.
Back it up before the first flash anyway:
esptool.py --chip esp32s3 --port <port> read_flash 0x9000 204800 nvsfactory.bin
Use the USB-C port on the bottom edge; the one on the back only supplies power. The data port is a WCH USB-to-dual-UART bridge, so it shows up as two serial ports, one for the ESP32-S3 and one for the Himax chip. Try each until the boot log appears. The console runs on the ESP32-S3's UART0, at 115200 baud.
Build without touching a connected device:
cd firmware/esp32
pio run -e sensecap-watcher
For simulator coverage use hermes-gadget sim --board sim-412x412-round.
Compilation and simulation are not physical verification; keep this profile
experimental until the checklist in hardware validation
has been completed for the exact W1-A revision.
Waveshare ESP32-S3-Touch-LCD-1.47
Board option esp32-s3-touch-lcd-147, for the 1.47" module: an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a 172×320 panel used landscape (320×172) and an AXS5106L touchscreen. This board has no microphone, speaker or audio codec, so it works as a text gadget: Hermes replies, cards and prompts appear on the screen and typed messages go out the USB console. Holding TALK shows that no microphone is available. Nothing needs wiring. The microSD slot and the battery ADC stay unused.
The glass is a JD9853. The first image drives it with the existing ST7789 SPI path, which is how Waveshare's Arduino demo constructs this panel (native 172×320, column offset 34, IPS off). The firmware swaps the axes so the UI is 320×172 and the column offset lands on the short side. If the panel stays blank, the next step is a JD9853 init table, recorded with its source and license. Do not flash the 1.46 image onto this board: that one is a round 412×412 QSPI panel.
| Part | Chip | Connection |
|---|---|---|
| Display | ST7789 path, JD9853 glass | SPI: SCK 38, MOSI 39, CS 21, DC 45, RST 40; landscape 320×172 (native 172×320, column offset 34 on the short side), no mirror. Text is drawn at twice the automatic size. The mascot is the 64 px bitmap |
| Backlight | GPIO 46, active high | |
| Touch | AXS5106L | I2C SDA 42, SCL 41, address 0x63, RST 47, INT 48 |
| Button (to GND) | TALK = BOOT (0). Swipe down cancels |
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e esp32-s3-touch-lcd-147 -t upload -t monitor
Or with idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32-s3-touch-lcd-147/sdkconfig.defaults" build. The USB-C port is the S3's own USB Serial/JTAG, so flashing and the serial console (115200 baud) both use it. A 320×172 simulator profile is sim-320x172-nospeaker.
First flash: what to check
This port is written from the Waveshare schematic and the Arduino demo's ST7789 offsets. On the first flash:
- Boot log:
st7789 320x172 readyandtouch ready. Inhermes-gadget diagthe parts line should list the display, and thei2clist should include0x63. - Screen: the mascot is upright in landscape on the glass, and the accents are amber, not blue. Portrait needed an X mirror; landscape does not, because the axis swap already turns that scan around. A blank panel means the JD9853 needs its own init table, or SPI mode 3. The column offset is 34 on the short side after the axis swap; a picture shifted off the glass means that offset is on the wrong axis.
- Touch: a tap answers yes and a swipe down cancels. Holding the screen or BOOT reports that no microphone is available.
- Text: a paired Hermes card, prompt or notice should render on the display. A timer alarm is silent.
Record the results with the hardware checklist.
Pin numbers: Waveshare schematic. The column offset and the ST7789 construction come from Waveshare's Arduino demo for this board. The AXS5106L report is register 0x01, read as a stopped write of that address and then a separate read. The low nibble of the next byte is the point count, then 12-bit X and Y. The parser is in-tree; no third-party touch driver is vendored.
Waveshare ESP32-S3-Knob-Touch-LCD-1.8
Use esp32s3-knob-touch-lcd-1.8 for the knob board: an ESP32-S3R8 with 16 MB flash and 8 MB octal PSRAM, a round 360×360 SH8601 LCD over QSPI (not the ST77916 of the 1.85C V2), CST816S touch, one PDM microphone, a rotary encoder around the screen, a DRV2605 haptic driver and a Li-ion battery with charging management.
This port is text-only. It doesn't drive the board's PCM5100A DAC and 3.5 mm headphone jack, so replies are shown on the screen and never spoken. Waveshare's ESP-IDF audio demo plays through that DAC from the S3 (I2S BCLK 39, WS 40, DOUT 41); this port has not tried it. The clone Guition JC3636K518 uses the same hardware and should work the same way. This port is experimental; display, touch and microphone were verified on hardware (360×360 round, hold-to-talk).
| Part | Connection |
|---|---|
| SH8601 LCD, QSPI | CS 14, clock 13, D0–D3 15/16/17/18, reset 21, backlight 47 (LEDC) |
| CST816S touch | I2C 0x15, INT 9, reset 10 |
| I2C | SDA 11, SCL 12, 400 kHz |
| PDM microphone | CLK 45, DATA 46 |
| Rotary encoder | A 8, B 7 (each detent scrolls; the knob's push button is not wired) |
| BOOT | GPIO 0, TALK |
Hold the screen to talk, release to send, swipe down to cancel. The IMU, RTC, TF card, haptic driver and battery ADC are not used.
cd firmware/esp32
pio run -e esp32s3-knob-touch-lcd-18 -t upload -t monitor
For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32s3-knob-touch-lcd-1.8/sdkconfig.defaults" with a separate build directory and sdkconfig. The USB-C port handles flashing and the serial console (115200 baud); flipping the cable flashes the other MCU. The sim-360x360-knob simulator board has the same screen and audio capabilities.
References: Waveshare wiki and its ESP-IDF and Arduino demo, the source of the pins above and the SH8601 initialization table. The table's source is listed in THIRD_PARTY_NOTICES.
First flash: what to check
- The panel logs
sh8601 360x360 ready. The knob ships an SH8601 glass; if a future unit logs an ST77916 panel ID instead, it has a different panel and needs the ST77916 bring-up table. - The encoder scrolls the reply list; each detent is one step.
- The microphone captures on a hold: check the VU feedback on screen, and that released audio is recognized.
ESP32-S3-BOX
Use esp32-s3-box for the original Espressif ESP32-S3-BOX: 16 MB flash and 8 MB octal PSRAM. BOX-3 and BOX-Lite use other profiles. This port is experimental, with no physical report recorded.
| Part | Connection |
|---|---|
| ST7789 320×240 | SPI MOSI 6, clock 7, CS 5, DC 4, reset 48 (active low, shared with touch), backlight 45 |
| TT21100 touch | I2C 0x24, interrupt 3. The touch driver mirrors X. |
| I2C | SDA 8, SCL 18, 400 kHz |
| ES8311 speaker / ES7210 microphones | MCLK 2, BCLK 17, WS 47, DOUT 15, DIN 16; amplifier enable 46 |
| BOOT | GPIO 0, TALK |
The glass is a 2.4 inch ST7789. Color order is BGR, both axes are mirrored, and color inversion stays off. Reset on GPIO 48 is active low. The display reset runs before touch starts, and touch does not pulse that line again. Backlight is GPIO 45. I2S word select is GPIO 47.
Hold the screen or BOOT to talk, swipe down to cancel, and hold the title for one second to open settings. GPIO 1 is the hardware mute button and is left to that circuit. The touch controller's home button is unused. The ICM-42607-P, the PMOD headers and storage stay off.
cd firmware/esp32
pio run -e esp32-s3-box -t upload -t monitor
The USB-C port handles flashing and the serial console. For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32-s3-box/sdkconfig.defaults" with a separate build directory and sdkconfig. Phone setup, pairing and OTA use the same flows as the other ESP32 boards.
Back up the factory image before the first flash:
esptool.py --chip esp32s3 read_flash 0 0x1000000 esp32-s3-box-factory.bin
On a good boot the panel logs st7789 320x240 ready. Run the hardware checklist for touch alignment, colors, audio, the physical mute button, USB recovery and Wi-Fi setup. No battery readings are advertised.
References: Espressif's ESP-BOX BSP at commit 67f41a169401d1f23e827188dd08fb351cb0febe (Apache 2.0). Pin numbers, the ST7789 mirror, BGR color order and the TT21100 mirror come from that package. The source of those facts is listed in THIRD_PARTY_NOTICES.
ESP32-S3-Korvo-2
Use esp32-s3-korvo-2 for the Espressif ESP32-S3-Korvo-2 with the LCD sub-board (ESP32-S3-Korvo-2-LCD V1.0 on a V3.0 or V3.1 main board): 16 MB flash and 8 MB octal PSRAM. This port is experimental, with no physical report recorded. A main board without that LCD sub-board has no panel.
| Part | Connection |
|---|---|
| ILI9341 320×240 | SPI MOSI 0, clock 1, DC 2. Chip select is not an ESP32 pin. Reset, backlight and the LCD/touch enable are on the TCA9554 |
| TCA9554 | I2C 0x38 (TCA9554A) or 0x20. Pin 3 held low enables the LCD and touch. Pin 2 is reset, pulsed low then left high. Pin 1 is the backlight, on when brightness is above 0 |
| GT911 or TT21100 touch | Probed at 0x5d, then 0x14, then 0x24. No interrupt pin. X is mirrored |
| I2C | SDA 17, SCL 18, 400 kHz |
| ES8311 speaker / ES7210 microphones | MCLK 16, BCLK 9, WS 45, DOUT 8, DIN 10; amplifier enable 48 |
| Battery | GPIO 6, divider of four. No charge pin and no software power-off |
The glass is a 2.4 inch ILI9341. Color order is BGR, both axes are mirrored, and color inversion stays off. The panel uses Espressif's stock ILI9341 initialization. SPI chip select stays disconnected. The expander enable is held before SPI and touch start.
Hold the screen to talk, swipe down to cancel, and hold the title for one second to open settings. GPIO 0 is the panel data line, so BOOT is not a talk button. The six ADC buttons on GPIO 5, the camera, the microSD card and the red and blue LEDs stay off.
cd firmware/esp32
pio run -e esp32-s3-korvo-2 -t upload -t monitor
The USB port handles flashing and the serial console. For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32-s3-korvo-2/sdkconfig.defaults" with a separate build directory and sdkconfig. Phone setup, pairing and OTA use the same flows as the other ESP32 boards.
Back up the factory image before the first flash:
esptool.py --chip esp32s3 read_flash 0 0x1000000 esp32-s3-korvo-2-factory.bin
On a good boot the panel logs ili9341 320x240 ready and the expander logs expander 0x38 levels ready or expander 0x20 levels ready. Run the hardware checklist for touch alignment, colors, audio, the battery reading and Wi-Fi setup. The battery percentage uses the default Li-ion estimate. No measured curve is claimed.
References: Espressif's Korvo-2 BSP at commit 67f41a169401d1f23e827188dd08fb351cb0febe (Apache 2.0), the Korvo-2 product page (16 MB flash and 8 MB PSRAM), and the Korvo-2-LCD user guide. Pin numbers, the ILI9341 mirror, BGR color order, the touch X mirror and the expander levels come from that package. The source of those facts is listed in THIRD_PARTY_NOTICES.
LCDWIKI ES3C28P
Use lcdwiki-es3c28p for the LCDWIKI ES3C28P (Shenzhen QDtech, spec sheet CR2025-MI6872 V1.0): a 2.8 inch IPS display module with an ESP32-S3, 16 MB QSPI flash and 8 MB octal PSRAM. Freenove's ESP32-S3 2.8 inch display uses the same pin map. The ES3N28P is the same board without the touchscreen and has no profile. This port is experimental, with a physical report on one unit.
| Part | Connection |
|---|---|
| ILI9341V 240×320 IPS | SPI MOSI 11, clock 12, CS 10, DC 46 (MISO 13 unused). Reset is CHIP_PU, shared with the ESP32-S3. Backlight 45, active high |
| FT6336G touch | I2C 0x38, reset 18, interrupt 17 |
| I2C | SDA 16, SCL 15, 400 kHz. Shared by the touch controller, the codec and the 4-pin I2C header |
| ES8311 speaker and microphone | MCLK 4, BCLK 5, WS 7, DOUT 8, DIN 6. The onboard MEMS microphone goes into the ES8311's ADC |
| Speaker amplifier | Enable on GPIO 1, active low, held low from boot as a power rail. 1.25 mm 2-pin speaker jack, up to 1.5 W at 8 Ω or 2 W at 4 Ω |
| Battery | GPIO 9 (ADC1 channel 8), 200 kΩ/200 kΩ divider. 3.7 V Li-polymer on a 1.25 mm 2-pin jack. No charge pin and no software power-off |
The panel runs in portrait with X mirrored, the usual ILI9341 portrait setting: upstream runs it in landscape with only the axis swap, so the unflagged scan is a mirror image. Portrait keeps the touch controller's own axes, because the FT5x06 touch path applies no swap or mirror; on the tested unit touch lines up with the picture up to the edges and corners. If it lands mirrored on another unit, the profile alone cannot correct it. Color order is BGR and color inversion is on, as in upstream's setup. The SPI clock is 20 MHz, as upstream uses. To preview the layout, run hermes-gadget sim --board sim-240x320.
Hold the screen or BOOT to talk and swipe down to cancel. RESET is CHIP_PU. The RGB LED on GPIO 42 has a built-in control IC, so the plain led.set action does not drive it and it stays off. The microSD slot (SDIO on GPIO 38 to 41, 47 and 48), the UART header and the extension pins (GPIO 2, 3, 14 and 21) are unused.
Back up the factory image before the first flash:
esptool.py --chip esp32s3 read_flash 0 0x1000000 lcdwiki-es3c28p-factory.bin
cd firmware/esp32
pio run -e lcdwiki-es3c28p -t upload -t monitor
The USB-C port handles flashing and the serial console. Hold BOOT, press and release RESET, then release BOOT to force download mode. For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/lcdwiki-es3c28p/sdkconfig.defaults" with a separate build directory and sdkconfig. Phone setup, pairing and OTA use the same flows as the other ESP32 boards.
On a good boot the panel logs ili9341 240x320 ready. Run the hardware checklist first for orientation and colors, then touch alignment at the four corners, the speaker (no sound means check the amplifier enable on GPIO 1), the microphone, the battery reading and Wi-Fi setup. The board reports the battery as a voltage only: with a single-cell 3.7 V Li-ion battery fitted, set battery_estimate liion turns on a rough percentage (battery indicator). No measured curve is claimed.
References: the LCDWIKI ES3C28P & ES3N28P product specification sheet V1.0 (2025-06-14), for the pin mapping, the FT6336G address and the active-low amplifier enable; and xiaozhi-esp32's freenove-esp32s3-display-2.8-lcd board at commit d91d6824309d12df5fc3db5edf8145ee829135d7 (MIT), for the ES8311 codec, the inverted amplifier enable, color inversion, BGR order, the SPI clock and the battery divider. The source of those facts is listed in THIRD_PARTY_NOTICES.
ESP32-S3-BOX-3
Use esp32-s3-box-3 for Espressif's BOX-3 with 16 MB flash and 16 MB octal PSRAM. The original BOX has its own profile. BOX-Lite needs a different profile. This port is experimental, with no physical report recorded.
| Part | Connection |
|---|---|
| 320×240 LCD | SPI MOSI 6, clock 7, CS 5, DC 4, shared reset 48 active high, backlight 47 |
| Touch | TT21100 at 0x24 or GT911 at 0x5D/0x14; interrupt 3 |
| I2C | SDA 8, SCL 18 |
| ES8311 speaker / ES7210 microphones | MCLK 2, BCLK 17, WS 45, DOUT 15, DIN 16; amplifier enable 46 |
| BOOT | GPIO 0, TALK |
The driver identifies the display revision through the touch controller, following Espressif's board definitions. TT21100 selects ST7789; GT911 selects the ILI9342 initialization sequence through the ILI9341 driver. An unknown controller leaves the display unavailable and records an error. The display resets the shared line once before touch initialization.
Hold the screen or BOOT to talk, swipe down to cancel, and hold the title for one second to open settings. The top mute button keeps its hardware function; it is not a CANCEL button. The front home key is unused. Dock sensors, expansion outputs and storage are not exposed by this profile.
cd firmware/esp32
pio run -e esp32-s3-box-3 -t upload -t monitor
The USB-C port handles flashing and the serial console. For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32-s3-box-3/sdkconfig.defaults" with a separate build directory and sdkconfig. Phone setup, pairing and OTA use the same flows as the other ESP32 boards.
Run the hardware checklist for the exact panel revision. Check touch alignment in all corners, display colors, audio interruption, the physical mute button, USB recovery and Wi-Fi setup. The settings menu provides local mic, speaker, display and input checks. No battery readings are advertised.
References: Espressif hardware overview and board definitions. Display and touch drivers keep their Apache 2.0 license; see README and the license archive distributed with firmware releases.
M5Stack CoreS3
Use m5stack-cores3 for the CoreS3 K128 with 16 MB flash and 8 MB quad PSRAM. Core, Core2 and CoreS3 SE are not covered by this profile. The port is experimental for both LCD revisions; a camera capture check covers one ILI9342C unit, but full physical reports remain outstanding.
| Part | Connection |
|---|---|
| 320×240 LCD | MOSI 37, clock 36, CS 3, DC 35; reset through AW9523 P1_1 |
| FT6336 touch | I2C 0x38; reset through AW9523 P0_0; polled |
| I2C | SDA 12, SCL 11 |
| AW88298 speaker / ES7210 microphones | MCLK 0, BCLK 34, WS 33, DOUT 13, DIN 14; reset through AW9523 P0_2 |
| Power and backlight | AXP2101 at 0x34; AW9523 at 0x58; boost enable P1_7 |
The display selects ILI9342C for touch firmware ID 0x10 and ILI9342E for 0x12. Other touch IDs (including 0x05) do not identify an LCD revision: the port probes the LCD registers directly over its 3-wire SPI connection before selecting either initialization table. It logs the read-back values and leaves the display unavailable if neither panel signature answers; it does not assume C for an unknown panel. M5Stack changed the LCD to ILI9342E in August 2026, so record the detection log and panel revision with test results.
The profile selects BGR color order, as specified by Espressif's CoreS3 BSP display header. This is independent of the RGB565 byte order on the SPI wire. Use settings Display check to verify red, green, blue, white and black on the actual panel; a readable screen alone does not establish correct colors.
Hold the screen to talk, swipe down to cancel, and hold the title for one second to open settings. GPIO 0 carries the audio clock and is not a TALK button. The hardware power and reset buttons retain their functions. The camera is the camera.capture action and a local camera mode (the settings menu's Camera item, below); the IMU, RTC, SD storage and expansion outputs are not exposed.
The power adapter enables the audio supplies (ALDO1 at 1.8 V and ALDO2 at 3.3 V), the onboard boost, and peripheral reset lines. Camera start-up turns on the camera ribbon's supplies (ALDO3 at 3.3 V, BLDO1 and BLDO2, as in esp-bsp's CoreS3 camera bring-up), which the camera and the proximity sensor share, pulses the camera enable on AW9523 P1_0, and starts the pipeline — when the camera mode opens or the first capture arrives, not at boot; see Camera (GC0308) for the start/stop lifecycle. Brightness controls the DLDO1 backlight supply between 2.5 and 3.3 V; zero disables that rail. It preserves charger settings, other rail settings and USB/bus output-enable bits. Settings provide battery readings, local power-off, screen timeout and hardware checks.
cd firmware/esp32
pio run -e m5stack-cores3 -t upload -t monitor
For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/m5stack-cores3/sdkconfig.defaults" with a separate build directory and sdkconfig. Use the USB-C data port for flashing and the console. To enter download mode, hold RESET for about three seconds until the green indicator lights. Phone Wi-Fi setup, pairing and OTA use the standard ESP32 flows.
Camera (GC0308)
The CoreS3's GC0308 camera (0.3 MP VGA, on the same ribbon cable as the
LTR-553ALS-WA proximity sensor) is available as a camera.capture action. The
adapter drives the sensor's power/reset over AW9523B P1_0, the SCCB hangs off
the internal I2C bus (AXP2101 and AW9523 share it), and the DVP pins come
straight from M5Stack's CoreS3 camera table:
| GC0308 pin | ESP32-S3 GPIO |
|---|---|
| SCCB SIOC | 11 |
| SCCB SIOD | 12 |
| XCLK | none — the sensor runs from its on-board 20 MHz crystal, so the port never generates XCLK (the LCD_CAM divider still needs the rate) |
| VSYNC | 46 |
| HREF | 38 |
| PCLK | 45 |
| D0–D7 | 39, 40, 41, 42, 15, 16, 48, 47 |
| CAM_RST | AW9523B P1_0 |
Captures are 640×480 tightly packed RGB565, byte-swapped on-device to the little-endian layout the gateway documents; the frame buffer lives in PSRAM. The driver is esp32-camera.
The camera also has a camera mode: the settings menu's Camera item
(shown only on boards whose port provides a camera) opens the device's own
camera screen. The live view is the VGA stream blitted straight into the panel
rows between the bars at about 10 fps, mirrored left-to-right like a
phone's front camera so the view moves the way a hand aimed at it moves — the
held photo (it lives only in the mode's memory, discarded on retake or
leaving) and the camera.capture action keep the sensor's own handedness.
The mode keeps the capture pipeline's frame size, because the driver queues
only frames as large as its frame-buffer allocation. A tap starts a 3-second
countdown (a large number over the live view) and captures; the photo stays on
screen until the next tap (retake: the live view comes back first) or a swipe
down leaves. The screen never dims while the camera is out, and the mode
leaves itself after 60 s with no touch.
The pipeline starts when the camera mode opens or the first camera.capture
arrives, and stops — while the camera mode is closed — when it leaves, or 60 s
after the last capture (an open mode stays up; closing it stops the pipeline
at once): the driver's frame buffers go back to PSRAM, the sensor is held in
reset, and the ribbon's supplies (ALDO3 at 3.3 V, BLDO1 and BLDO2) go off. A
start that fails hides the Camera item and refuses captures until the next
restart. On a board without touch, camera on the serial console opens the
mode and camera close leaves.
Before relying on the port, run the physical checklist, including all touch corners, LCD colors, microphone level, speaker playback and interruption, backlight range, USB recovery, and battery shutdown/wake. Test USB and battery power separately.
References: M5Stack hardware and recovery instructions, Espressif board definitions, AW9523 registers, and AXP2101 registers. See README for driver licenses and the adapted ILI9342E table's notice.
Waveshare ESP32-S3-Touch-AMOLED-1.32
Board option waveshare-touch-amoled-132, for the Waveshare ESP32-S3-Touch-AMOLED-1.32: an ESP32-S3-PICO-1-N8R8 with 8 MB flash and 8 MB octal PSRAM, a round 1.32" 466×466 CO5300 panel over QSPI, a CST820 touchscreen, and one ES8311 codec for the speaker and the microphone. This port is experimental. It has not been run on a board.
Back up the whole flash before the first flash. The board has no other copy of its factory firmware:
esptool.py --chip esp32s3 read_flash 0 0x800000 touch-amoled-132-factory.bin
Writing that file back at 0x0 restores the original firmware.
| Part | Connection |
|---|---|
| CO5300 466×466 AMOLED, QSPI | CS 10, clock 11, D0–D3 12/13/14/15, reset 8; 40 MHz; column offset 6 |
| CST820 touch | I2C 0x15 on SDA 47, SCL 48; reset 7; interrupt 6 unused because input is polled |
| ES8311 speaker and microphone | I2C 0x18 on the same bus; MCLK 38, BCLK 39, WS 41, DOUT 42, DIN 40; amplifier enable 46 |
| Power latch | GPIO 18 held high. PWR is GPIO 17 |
| BOOT | GPIO 0, TALK |
Hold the screen or BOOT to talk, tap to answer yes, and swipe down to cancel. A short press on PWR turns the screen off and on. Holding PWR drops GPIO 18, which releases the battery latch. USB can still power the board after that. The round 466 layout is the existing sim-466x466-round simulator profile. That profile also has a motion sensor, and this board does not.
The CO5300 bring-up is the short table from Waveshare's board support package, with a 100 ms wait after sleep-out. The 1.75" table writes extra registers and waits 600 ms, so this profile does not use it. xiaozhi-esp32 writes memory-access control 0xC0 after init, which rotates the picture 180 degrees. This profile does not. If a unit shows the picture upside down, that register is the first thing to check.
The product has a lithium-battery header. Neither the board support package nor the pin list that names GPIO 17 and GPIO 18 names a battery-sense pin, so this profile does not report voltage or a percentage. Do not add a divider ratio without a schematic.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e waveshare-touch-amoled-132 -t upload -t monitor
Or with idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/waveshare-esp32-s3-touch-amoled-1.32/sdkconfig.defaults" build. The USB-C port is the module's USB Serial/JTAG, so flashing and the serial console (115200 baud) both use it.
First flash: what to check
- Boot log:
CO5300 466x466 readyandcodecs: speaker ready, microphones ready (es8311 analog).hermes-gadget diagshould list the display and I2C devices0x18and0x15. - Screen: the mascot is upright inside the round glass, and the colors are right. A picture that is upside down is a candidate for memory-access control
0xC0. A shifted picture means the column offset of 6 is wrong. - Touch: holding the screen records, a swipe down cancels, and taps land where you touch.
- Microphone and speaker: hold BOOT and speak; the waves move with your voice. Replies are clear (
set volume 80). - Power: on battery, a short PWR press turns the screen off and on, and holding PWR powers the board off. GPIO 18 must stay high while the board should remain on.
statusdoes not show a battery voltage.
Pin numbers, the CO5300 command bytes and the column gap follow Waveshare's esp32_s3_touch_amoled_1_32 board support package at commit b9a73081. GPIO 17 and GPIO 18 follow xiaozhi-esp32's waveshare/esp32-s3-touch-amoled-1.32 board at commit 49b4380b (tag v2.5.2). See THIRD_PARTY_NOTICES.
Waveshare ESP32-S3-Touch-AMOLED-1.43C
Board option waveshare-touch-amoled-143c, for the Waveshare ESP32-S3-Touch-AMOLED-1.43C: an ESP32-S3-PICO-1-N8R8 with 8 MB flash and 8 MB octal PSRAM, a round 1.43" 466×466 CO5300 panel over QSPI, a CST820 touchscreen, an ES8311 speaker and ES7210 microphones. This port is experimental. It has not been run on a board.
This is not the older ESP32-S3-Touch-AMOLED-1.43. That board has 16 MB flash, a different pin map, an IMU and an RTC. Do not flash this image onto it.
Back up the whole flash before the first flash. The board has no other copy of its factory firmware:
esptool.py --chip esp32s3 read_flash 0 0x800000 touch-amoled-143c-factory.bin
Writing that file back at 0x0 restores the original firmware.
| Part | Connection |
|---|---|
| CO5300 466×466 AMOLED, QSPI | CS 15, clock 14, D0–D3 9/10/11/12, reset 13; 40 MHz; column offset 8; memory-access control 0xC0 |
| CST820 touch | I2C 0x15 on SDA 47, SCL 48; reset 16; interrupt 17 unused because input is polled; both axes mirrored to match the panel |
| ES8311 speaker | I2C 0x18 on the same bus; MCLK 38, BCLK 39, WS 40, DOUT 41, DIN 42; amplifier enable 46 |
| ES7210 microphones | I2C 0x40 on the same bus; MIC1 and MIC2. MIC3 is the playback reference and stays off |
| Codec supply | GPIO 18 held high. This is the audio LDO, not a battery latch |
| Battery | GPIO 4, ADC1 channel 3, calibrated millivolts times 2. GPIO 7 is low while charging. GPIO 5 is the charge LED and is unused |
| BOOT | GPIO 0, TALK |
| Tearing | GPIO 8, unused |
Hold the screen or BOOT to talk, tap to answer yes, and swipe down to cancel. There is no power key and no software power-off. The round 466 layout is the existing sim-466x466-round simulator profile. That profile also has a motion sensor, and this board does not.
The CO5300 bring-up follows the factory component: the short table, a 120 ms wait after sleep-out, a column offset of 8, and a 180 degree rotation. The 1.32" table uses a column offset of 6 and does not rotate, so this profile does not use it. The factory table itself leaves the pixel format and the window to the CO5300 driver, writes brightness 0x00, then mirrors both axes. This driver sends those steps in the same table and writes brightness 0xFF, which is the factory default of 100%. A shifted picture means the column offset of 8 is wrong.
GPIO 4 reports a voltage. It does not report a percentage until set battery_estimate liion. The divider ratio comes from the vendor example (calibrated millivolts * 2). It is not a measured curve. status shows battery_mv and charging.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e waveshare-touch-amoled-143c -t upload -t monitor
Or with idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/waveshare-esp32-s3-touch-amoled-1.43c/sdkconfig.defaults" build. The USB-C port is the module's USB Serial/JTAG, so flashing and the serial console (115200 baud) both use it.
First flash: what to check
- Boot log:
CO5300 466x466 readyandcodecs: speaker ready, microphones ready (es7210).hermes-gadget diagshould list the display and I2C devices0x18,0x40and0x15. - Screen: the mascot is upright inside the round glass, and the colors are right. A shifted picture means the column offset of 8 is wrong.
- Touch: holding the screen records, a swipe down cancels, and taps land where you touch. A touch that lands opposite the picture means the 180 degree mirror is wrong.
- Microphone and speaker: hold BOOT and speak; the waves move with your voice. Replies are clear (
set volume 80). - Power:
statusshowsbattery_mvwith a cell fitted, andchargingwhile the charger is active. GPIO 18 must stay high or the codecs have no supply. There is no power-off command.
Pin numbers, the CO5300 command bytes, the column gap, the codec supply and the battery divider follow Waveshare's ESP32-S3-Touch-AMOLED-1.43C repository at commit 8cea11dd. See THIRD_PARTY_NOTICES.
ESP32-S3-Touch-AMOLED-1.75C
Use esp32s3-touch-amoled-175c for SKUs 33691/33692, the enclosed model with 32 MB flash and 8 MB octal PSRAM. This is an experimental port. Use its exact image; the 1.75 model's image has different pins.
| Part | Connection |
|---|---|
| CO5300 466×466 AMOLED | QSPI CS 12, clock 38, D0–D3 4/5/6/7, reset 1; column offset 6 |
| CST9217 touch | I2C 0x5A, reset 2; interrupt 11 unused because input is polled |
| I2C | SDA 15, SCL 14, 400 kHz |
| ES8311 speaker / ES7210 microphones | MCLK 16, BCLK 9, WS 45, DOUT 8, DIN 10; amplifier enable 46 |
| AXP2101 | I2C 0x34; ALDO1 at 3.3 V supplies analog audio; reports PWR short presses |
| BOOT | GPIO 0, TALK |
Hold the screen or BOOT to talk. Swipe down to cancel. Hold the SETTINGS target at the top of the screen for one second to open settings. A short press of PWR turns the screen off, and another press, a touch or BOOT turns it back on; Wi-Fi and the connection to Hermes stay up. PWR reaches only the AXP2101 on this model, so the firmware reads its short-press interrupt there; holding PWR keeps the PMIC's own power behavior. There is no TCA9554 expander. The IMU and RTC are not exposed.
The firmware enables ALDO1 for audio while preserving the other rails and charging settings. To save battery, the amplifier (GPIO 46) is powered only while sound plays, the ES7210 microphones only while recording, and the CPU drops from 240 to 80 MHz when idle (ESP-IDF power management). On battery, with the screen off and nothing happening, it also light-sleeps between events while staying connected to Wi-Fi and Hermes. It stays awake while it reconnects to Hermes, including for as long as Wi-Fi is up but Hermes can't be reached; on USB it never light-sleeps, so the serial console, flashing and JTAG keep working. Battery readings and local power-off use the existing AXP2101 driver. An unavailable ADC or gauge reading remains absent. Use the settings menu for microphone, speaker, display, touch, volume, brightness and power checks.
Build and flash over the board's USB-C data port:
cd firmware/esp32
pio run -e esp32s3-touch-amoled-175c -t upload -t monitor
For ESP-IDF, use SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32s3-touch-amoled-175c/sdkconfig.defaults" with a separate build directory and sdkconfig. The release workflow packages a distinct image and board identity, which prevents installing another model's OTA image.
Before relying on the port, run the physical checklist. Check screen orientation and edges, touch alignment, microphone level, a spoken reply, Wi-Fi setup and USB recovery. Test charging, shutdown and wake separately on USB and battery. A physical report for SKU 33691 is recorded. It ran on a working branch rather than a build of main, so the port stays experimental.
Pin and supply references: Waveshare schematic and manufacturer board definitions. The port reuses the existing CO5300, CST9217 and Espressif codec drivers; see the license notes.
LilyGO T-Display-S3
Board option tdisplay-s3, for LilyGO's 1.9" module: an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a 170×320 ST7789 panel, two buttons, a battery charger and a battery voltage divider. This board has no microphone, speaker or audio codec, so it works as a text gadget: Hermes replies, cards and prompts appear on the screen and typed messages go out. Holding TALK shows that no microphone is available. Nothing needs wiring.
Unlike the SPI panels above, this one puts the ST7789 on an 8-bit i80 parallel bus, so the port drives the LCD_CAM unit instead of SPI.
| Part | Chip | Connection |
|---|---|---|
| Display | ST7789, i80 | D0–D7 39/40/41/42/45/46/47/48, DC 7, WR 8, CS 6, RST 5; gap (0, 35); 320×170 landscape |
| Backlight | AW9364 | GPIO 38, 16-level pulse-count brightness control |
| Panel power | GPIO 15, high before the panel starts | |
| Battery | GPIO 4 ADC through a 1:2 divider; no fuel gauge, so no percentage | |
| Buttons (to GND) | TALK = BOOT (0), CANCEL = Button2 (14) |
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e tdisplay-s3 -t upload -t monitor
Or with idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/tdisplay-s3/sdkconfig.defaults" build. The USB-C port is the S3's own USB Serial/JTAG, so flashing and the serial console (115200 baud) both use it.
First flash: what to check
This port is written from LilyGO's published pinout and examples. On the first flash:
- Boot log:
ST7789 320x170 ready on the i80 bus (gap 0,35). Inhermes-gadget diagthe parts line should readdisplay st7789-i80. - Screen: the mascot is centred, upright and not mirrored. If it is mirrored, swap
mirror_x/mirror_y. A thin stripe at one edge means the gap is off — LilyGO warns that it is panel-specific even within one driver IC, so try neighbouring values and record what your panel needs. - GPIO 15: the panel rail. On battery power the screen stays dark unless this pin is high; the driver raises it before initialising the panel.
- Buttons: BOOT is TALK and Button2 cancels. With no microphone, holding TALK flashes "Microphone unavailable" — that is expected on this board, not a fault.
- Text:
say helloover the console, or a paired Hermes, should render on the display. - Backlight: check low and full brightness, then let the idle timer turn the screen off and wake it immediately. Brightness should return to the selected setting.
Free GPIOs after the panel, buttons and battery: 1, 2, 3, 10, 11, 12, 13. An I2S microphone and amplifier need six of them, so voice is possible with external modules; the i80 bus uses LCD_CAM and audio uses I2S, so the two do not collide.
Pins and the panel setup follow LilyGO's T-Display-S3 examples (examples/factory) and the pin map. No physical verification report is recorded yet; see the hardware validation table.
ESP32-S3-Touch-AMOLED-1.75
Board option esp32s3-touch-amoled-175, for Waveshare's all-in-one board: an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a 1.75" 466×466 AMOLED, touch, two microphones, a speaker output, a battery charger and an optional case. Nothing needs wiring; plug a small 8 Ω speaker into the SPK connector to hear replies.
| Part | Chip | Connection |
|---|---|---|
| Display | CO5300, QSPI | CS 12, SCLK 38, D0–D3 4/5/6/7, RST 39; column offset 6 |
| Touch | CST9217 | I2C 0x5A, RST 40 (INT 11 unused: polled) |
| Speaker DAC | ES8311 | I2C 0x18; I2S MCLK 42, BCLK 9, WS 45, DOUT 8; amplifier enable 46 |
| Microphones | ES7210 | I2C 0x40; I2S DIN 10 (shares the bus above), MIC1 + MIC2 |
| Power | AXP2101 | I2C 0x34; battery/USB readings and local power-off; charging and rails keep their defaults |
| I/O expander | TCA9554 | I2C 0x20; P4 mirrors the PWR key |
| Motion sensor | QMI8658 | I2C 0x6B; accelerometer only, read at 10 Hz (face-down sleep) |
| Clock chip | PCF85063 | I2C 0x51; keeps the time in UTC across resets, set from network time (resting clock) |
| I2C bus | SDA 15, SCL 14, 400 kHz | |
| BOOT key | GPIO 0 |
Controls. The screen is the main input:
| Do this | Does |
|---|---|
| Hold the screen | TALK: speak while holding, lift to send |
| Tap the screen | Answer "yes" to a question |
| Swipe down | CANCEL: discard a recording, close a card, stop a turn, answer "no" |
| Press the side PWR key | CANCEL as well; hold it 2 s for a new conversation |
| Hold BOOT | TALK, like holding the screen |
set touch_cancel swipe keeps only the swipe as CANCEL, set touch_cancel pwr only the PWR key, and set touch_cancel both restores the default. The same gestures work on the sim-466x466-round simulator board with the mouse.
The device settings menu shows battery voltage, the PMIC's estimated percentage, charging and USB power. When the gauge reports no valid estimate, the percentage is estimated from the cell voltage on a linear 3.3 to 4.2 V scale instead; that estimate reads high while charging. The AMOLED-1.75C uses curves measured on its 500 mAh cell instead. On battery, the percentage follows a discharge curve at the median voltage of the last minute and never rises until the board is charged. While charging, it follows a charge curve, never falls, and stays at most 99% until the AXP2101 reports charging done, then shows 100, including while the AXP2101 later tops up the cell on USB. The discharge curve was measured at about 93 mA with the screen off, so a heavier load reads a few points low, and its 80 to 95% range is extrapolated. The charge curve assumes the charge current stays constant; diag reports the AXP2101's limit as charge_current_ma (200 mA on the measured board, set in eFuse; the datasheet's charger section gives 300 mA). Readings refresh every five seconds and appear in status, diag and Hermes sensor telemetry. Failed reads become unavailable; they do not retain a stale percentage. A low gauge estimate, 10 percent or less without USB, adds a reminder on the idle screen. The battery indicator, off by default, can show the same percentage at the top of the screen.
Select Power off twice to request shutdown through the AXP2101. Use PWR to turn the board on again. This is a local control; Hermes has no power-off action. USB power may affect shutdown and wake behavior, so test both power sources on your board revision. The physical PWR key retains its existing Cancel behavior and the PMIC's own long-hold behavior.
The driver follows X-Powers' AXP2101 register documentation. It reads status, enabled measurements and gauge estimates. It does not change charging current, battery protection, gauge calibration or supply voltages. Battery estimates depend on the fitted cell. Physical power tests remain outstanding in the verification table.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e esp32s3-touch-amoled-175 -t upload -t monitor
The USB-C port is the S3's own USB. It shows up as a "USB JTAG/serial debug unit" (a COM port on Windows), and both flashing and the serial console use it.
First flash: what to check
This port is written from Waveshare's published pinout and drivers. On the first flash, go through this list, and for anything that looks wrong send the report from hermes-gadget diag --port COMx:
- Boot log:
CO5300 466x466 ready,codecs: speaker ready, microphones readyandtouch ready, key ready. Adid not answerormissingline names the part to look at. Thehg.diaglines sum it up: reset reason, memory, andparts: display co5300, microphone es7210, speaker es8311, touch yes, key yes, imu qmi8658, rtc pcf85063. In thediagreport,i2cshould include0x18(ES8311),0x20(TCA9554),0x34(AXP2101),0x40(ES7210),0x51(PCF85063),0x5a(CST9217) and0x6b(QMI8658). Thediagreport also has atimeobject once the clock chip or the network supplies the time. - Console:
hermes-gadget console --port COMxon the USB-C port answersstatus. If the log shows but commands get no answer, the console is still on UART0. - Screen: the mascot is centred, upright and not mirrored, and the colours are right (amber accents, not blue). A thin stripe at one edge means the column offset is off.
- Touch: hold the screen and the listening waves appear; a swipe down (not up) cancels. A reversed swipe means the touch mirroring needs flipping.
- PWR key: a short press cancels and holding 2 s starts a new conversation without powering the board off.
- Microphone: say something; the waves move with your voice, and Hermes's transcript is right.
- Speaker: replies are clear and loud enough (
set volume 80); no hiss between replies.
ESP32-S3-Touch-AMOLED-1.8
Board option esp32s3-touch-amoled-18, for Waveshare's rectangular 1.8" board, V2 only (CO5300 display, CST820 touch): an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a 368×448 AMOLED, one analog microphone, a speaker output and a battery. Nothing needs wiring; plug a small 8 Ω speaker into the SPK connector to hear replies.
The V1 board uses a different panel and touch controller, and this image doesn't support it. The 1.75" models also need their own profile: different pins, a round panel and different codecs.
| Part | Chip | Connection |
|---|---|---|
| Display | CO5300, QSPI | CS 12, SCLK 11, D0–D3 4/5/6/7; reset through the TCA9554 (LCD_RST); column offset 16 |
| Touch | CST820 | I2C 0x15, read with the CST816 report format; reset through the TCA9554 (TOUCH_RST); INT 21 unused (polled) |
| Speaker DAC + microphone ADC | ES8311 | I2C 0x18; I2S MCLK 16, BCLK 9, WS 45, DOUT 8, DIN 10; amplifier enable 46 |
| Microphone | ES8311 analog input | One analog electret microphone into the ES8311's own ADC (not an ES7210) |
| Power | AXP2101 | I2C 0x34; battery/USB readings and local power-off; charging and rails keep their defaults |
| Reset expander | TCA9554 | I2C 0x20; drives LCD_RST (P0), the display power rail (P1) and TOUCH_RST (P2); reads the PWR key (P4, high while pressed) |
| I2C bus | SDA 15, SCL 14, 400 kHz | |
| BOOT key | GPIO 0 |
The display and touch controllers are held in reset by the TCA9554, not by direct GPIOs. Before the display starts, the firmware pulls P0–P2 low for 20 ms, releases them and waits 150 ms; the other expander pins keep their state.
Controls. Hold the screen to talk, tap to answer "yes", swipe down to cancel; hold BOOT to talk as well. PWR is CANCEL: a press cancels, and holding it for two seconds starts a new conversation.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e esp32s3-touch-amoled-18 -t upload -t monitor
The USB-C port is the S3's own USB Serial/JTAG, used for both flashing and the serial console.
First flash: what to check
A smoke test on a V2 board confirmed the boot, the display and the I2C devices, and the codec, touch, speaker and microphone tasks started; touch, microphone capture, speaker playback and battery are untested (see hardware validation). On the first flash, check:
- Boot log:
CO5300 368x448 ready,expander resets 0x07 ready,codecs: speaker ready, microphones ready (es8311 analog)andtouch ready, key off, encoder off. Thehg.diaglines should readparts: display co5300, microphone es8311, speaker es8311, touch yes, key no, imu none. In thediagreport,i2cshould include0x15(CST820),0x18(ES8311),0x20(TCA9554) and0x34(AXP2101). There is no ES7210 on this board. - Screen: the mascot is upright and not mirrored, and the colours are right (amber accents, not blue); a stripe at one edge means the column offset is off. If the image is shifted or the panel stays dark, the vendor init table is the first thing to revisit.
- Touch: holding the screen shows the listening waves and a swipe down cancels. If the coordinates are mirrored, flip
touch.mirror_x/mirror_yinboard.cpp. - Microphone: say something; the waves move with your voice and Hermes's transcript is right. The ES8311 analog input path is the part most likely to need its gain adjusted.
- Speaker: replies are clear and loud enough (
set volume 80); no hiss between replies.
The CO5300 start-up table comes from Waveshare's board support package at commit 9f4030c; see THIRD_PARTY_NOTICES.
ESP32-S3-Touch-AMOLED-2.06
Board option esp32s3-touch-amoled-206, for Waveshare's 2.06" AMOLED touch watch: an ESP32-S3R8 (8 MB octal PSRAM) with 32 MB flash, a 410×502 AMOLED with rounded corners, two microphones, an onboard speaker, a battery, an IMU, an RTC and a TF slot. Nothing needs wiring.
| Part | Chip | Connection |
|---|---|---|
| Display | CO5300, QSPI | CS 12, SCLK 11, D0–D3 4/5/6/7, reset 8; column offset 22; tearing-effect output on 13 (unused) |
| Touch | FT3168 | I2C 0x38, read with the FT5x06 driver; reset 9; INT 38, read on its falling edge (the idle chip dozes, refuses reads and reports its waking touch only briefly) |
| Speaker DAC | ES8311 | I2C 0x18; I2S MCLK 16, BCLK 41, WS 45, DOUT 40; NS4150B amplifier enable 46 |
| Microphones | ES7210 | I2C 0x40; two microphones on MIC1/MIC2 (MIC3 is the speaker loopback, unused); I2S DIN 42 |
| Power | AXP2101 | I2C 0x34; battery/USB readings, PWR short press and local power-off; charging and rails keep their defaults; battery percent from a measured discharge curve |
| Clock chip | PCF85063 | I2C 0x51; keeps the time in UTC across resets, set from network time (resting clock) |
| I2C bus | SDA 15, SCL 14, 400 kHz | |
| BOOT key | GPIO 0 | |
| Not used | QMI8658 IMU (I2C 0x6B), TF card |
The audio codecs and amplifier run from the always-on 3.3 V rail, so no AXP2101 rail is switched for audio. The UI uses rows 8–493 of the panel. The glass corners are rounded with a radius of about 100 px (measured with a test grid), so the status row also keeps its text 64 px (corner_inset) in from the sides.
On battery the percentage follows a discharge curve measured on the watch's own cell (kAmoled206Curve), at the median voltage of the last minute, and never rises until the watch is charged; a full watch shows 100 right after unplugging. The AXP2101 gauge it replaces read low through most of a discharge: 25% with 42% left, the 15% alert with over two hours left, and 0% 11 minutes before shutdown. The curve comes from one full discharge of 8 h 14 min with light use and the screen mostly dark (battery report), so a heavier load reads a few points low. While charging the percentage is still the gauge's, and it shows 100 once the AXP2101 reports charging done: the cell reaches 4.18 V less than halfway through a charge, so the voltage can't tell how far the charge has got.
The microphones are quiet: speech averaged about 170 RMS at the default 24 dB gain, under tap mode's usual 500 floor. This profile sets 30 dB and a floor of 200 (codec.mic_gain_db, codec.vad_min_rms), and tap mode's noise estimate still raises the threshold in a loud room.
The CPU drops to 80 MHz when idle. While the screen is dark, on battery and idle, the chip also light-sleeps between Wi-Fi beacons, and once Hermes has been quiet for 10 s the radio wakes only every third beacon (Wi-Fi power save). The FT3168 reports a touch with one short INT pulse, and its report is gone about 20 ms later, so while dozing INT becomes a low-level wake source: a tap wakes the CPU, and the touch task reads the report right after. With touch_wake off, a doze leaves INT quiet, and only BOOT or PWR wakes the chip. Light sleep never runs while a USB host is connected (the console and JTAG would stop), so a doze shows only on battery. The partial physical report covers USB operation, and the light sleep report covers dozing on battery; the port stays experimental.
Two more hardware facts for anyone building on this board. The QMI8658 is mounted a quarter turn from the screen: its +x axis points to the screen's bottom, +y to its left and +z out of the back (checked by tilting the watch). The schematic's vibration motor is not fitted: there is a driver (an NPN from GPIO 18) and two pads, P1 (the AXP2101's ALDO3) and P2, for a motor.
Controls. Hold the screen to talk, tap to answer "yes", swipe down to cancel; hold BOOT to talk as well. A short press of PWR is read from the AXP2101; holding PWR for 6 s turns the watch off in hardware.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e esp32s3-touch-amoled-206 -t upload -t monitor
The USB-C port is the S3's own USB Serial/JTAG, used for both flashing and the serial console. If the port does not appear, hold BOOT while plugging in USB to enter download mode.
First flash: what to check
- Boot log:
CO5300 410x486 ready,codecs: speaker ready, microphones ready,touch read on INT (GPIO 38)andtouch ready, key off, encoder off. In thediagreport,i2cshould include0x18(ES8311),0x34(AXP2101),0x40(ES7210),0x51(PCF85063) and0x6b(QMI8658).0x38(FT3168) is listed only while the touch chip is awake: it dozes after a few idle seconds and doesn't answer then. When the PCF85063 answers, the parts line addsrtc pcf85063, anddiagreports atimeobject once the time is known. - Screen: the mascot is upright and not mirrored; text is white on dark slate bars, and the link dot is green once online. A stripe at one edge means the column offset is off. Text clipped by a rounded corner means
corner_insetneeds raising. - Touch: holding the screen shows the listening waves, and a swipe down cancels. Report mirrored coordinates with the board revision; this FT5x06 adapter does not apply
touch.mirror_xortouch.mirror_y. If they are 8 rows off, adjusttouch.offset_y. - Microphones: say something. The waves move with your voice and the transcript is right; in tap mode, a sentence spoken at arm's length starts and ends the recording.
- Speaker: replies are clear and loud enough (
set volume 80), with no hiss between replies. - Power: a short PWR press toggles the screen, and the battery reading appears with a cell attached.
The CO5300 start-up table and the pin map come from Waveshare's board support package 2.0.0 at commit 9daffb7, checked against the schematic; see THIRD_PARTY_NOTICES.
ESP32-S3-Touch-AMOLED-2.16
Board option esp32s3-touch-amoled-216, for Waveshare's 2.16" AMOLED touch development board (SKUs 33969 and 33970, the -EN version): an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a square 480×480 AMOLED, two microphones with echo-cancellation circuitry, a speaker output, an AXP2101 PMIC with an MX1.25 header for a 3.7 V lithium battery, an IMU, an RTC and a TF slot. Nothing needs wiring.
| Part | Chip | Connection |
|---|---|---|
| Display | CO5300, QSPI | CS 12, SCLK 38, D0–D3 4/5/6/7, reset 39; full 480×480 window, no column offset |
| Touch | CST9220 | I2C 0x5A, read with the CST9217 report; reset 40; INT 11; y mirrored, then x and y swapped, to match the display's MADCTL 0xA0, as in Waveshare's BSP |
| Speaker DAC | ES8311 | I2C 0x18; I2S MCLK 42, BCLK 9, WS 45, DOUT 8; amplifier enable 46 |
| Microphones | ES7210 | I2C 0x40; two microphones plus echo cancellation; I2S DIN 10 |
| Power | AXP2101 | I2C 0x34; battery/USB readings, PWR short press and local power-off; charging and rails keep their defaults |
| Clock chip | PCF85063 | I2C 0x51; keeps the time in UTC across resets, set from network time (resting clock) |
| I2C bus | SDA 15, SCL 14, 400 kHz | |
| KEY3 | GPIO 18 (not wired as a gadget control) | |
| BOOT key | GPIO 0 | |
| Not used | QMI8658 IMU (I2C 0x6B), TF card |
No AXP2101 output is switched for audio, as in Waveshare's BSP, which does not configure the PMIC. Battery operation has not been tested. This port stays experimental until a full physical verification report is recorded for the exact board.
Controls. Hold the screen or BOOT to talk, tap to answer "yes", swipe down to cancel. A short press on PWR turns the screen off and on. KEY3 (GPIO18) is not wired as a gadget control in this profile.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e esp32s3-touch-amoled-216 -t upload -t monitor
The USB-C port is the S3's own USB Serial/JTAG, used for both flashing and the serial console. If the port does not appear, hold BOOT while plugging in USB to enter download mode. If the board shows nothing and writes no log after flashing, unplug USB and plug it in again, with the battery disconnected if one is fitted, since it keeps the board powered: one unit without a battery stayed in download mode after a full image was written with esptool, until it was power-cycled (partial report).
First flash: what to check
- Boot log:
CO5300 480x480 ready,codecs: speaker ready, microphones ready, plustouch ready, key off, encoder off. In thediagreport,i2cshould include0x18(ES8311),0x34(AXP2101),0x40(ES7210),0x51(PCF85063),0x5a(CST9220) and0x6b(QMI8658). When the PCF85063 answers, the parts line addsrtc pcf85063, anddiagreports atimeobject once the time is known. - Screen: the mascot is upright and not mirrored; text is white on dark slate bars, and the link dot is green once online. A stripe at one edge means the column offset is off.
- Touch: holding the screen shows the listening waves, and a swipe down cancels. Report mirrored or offset coordinates with the board revision.
- Microphones: say something. The waves move with your voice and the transcript is right; in tap mode, a sentence spoken at arm's length starts and ends the recording.
- Speaker: replies are clear and loud enough (
set volume 80), with no hiss between replies.
The CO5300 start-up table and the pin map come from Waveshare's board support package 2.0.1 at commit 63ac675, checked against the product documentation; see THIRD_PARTY_NOTICES.
Xorigin AIPI Lite
Board option aipi-lite, for Xorigin's AIPI Lite: an ESP32-S3 with 16 MB flash and 8 MB octal PSRAM, a 128×128 ST7789 panel, one ES8311 codec for both the speaker and the microphone, BOOT and power keys, and a battery. This port is experimental.
Back up the factory data before the first flash. The AIPI Lite keeps its credentials for Xorigin's own service in a factory partition at 0x9000, where this firmware's settings start, so flashing Hermes Gadget overwrites it. Save it first:
esptool.py --chip esp32s3 read_flash 0x9000 16384 nvsfactory.bin
| Part | Chip | Connection |
|---|---|---|
| Display | ST7789, SPI | MOSI 17, SCLK 16, CS 15, DC 7, RST 18; 20 MHz, BGR; backlight GPIO 3 |
| Speaker DAC + microphone ADC | ES8311 | I2C 0x18 on SDA 5, SCL 4; I2S MCLK 6, BCLK 14, WS 12, DOUT 11, DIN 13; amplifier enable 9 |
| Power | GPIO 10 latches the supply on and powers the codec; charge signal on GPIO 8; battery divider on GPIO 2 (ADC1 channel 1) | |
| Keys | BOOT GPIO 42 (TALK), power GPIO 1 (CANCEL) |
The battery level and charging state aren't reported yet: the divider ratio on GPIO 2 hasn't been measured, and the charge signal's polarity isn't confirmed.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e aipi-lite -t upload -t monitor
The profile expects the USB-C port to be the S3's own USB Serial/JTAG, used for flashing and the serial console. That is inferred from the pin map and not yet confirmed on a board.
First flash: what to check
- Boot log:
battery latch enabled; no battery voltage readingandcodecs: speaker ready, microphones ready (es8311 analog). Thehg.diagparts line should readdisplay st7789, microphone es8311, speaker es8311. - Screen: the mascot is upright and not mirrored, and the colors are right (amber accents, not blue). Swapped red and blue means
lcd.bgrinboard.cppis wrong. - Microphone: hold BOOT and speak; the waves move with your voice and Hermes's transcript is right.
- Speaker: replies are clear and loud enough (
set volume 80). - Power: unplug USB with the battery in, and the device stays on. Power off in settings turns it off.
- Console:
hermes-gadget diaganswers over the USB-C port.
The pin map follows xiaozhi-esp32's xorigin/aipi-lite board at commit 0d576d3; see THIRD_PARTY_NOTICES.
M5Stack StickS3
Board option m5stack-sticks3, for M5Stack's StickS3: an ESP32-S3-PICO-1-N8R8 (8 MB flash, 8 MB octal PSRAM), a 1.14" 135×240 ST7789P3 panel used in landscape, one ES8311 codec for both the speaker and the microphone, an AW8737 amplifier, two keys, a BMI270 IMU and a 250 mAh battery behind an M5PM1 power manager. This port is experimental; see its verification status.
| Part | Chip | Connection |
|---|---|---|
| Display | ST7789P3, SPI | MOSI 39, SCLK 40, CS 41, DC 45, RST 21; backlight GPIO 38; 240×135 window at x 40, y 53 of the controller's RAM |
| Speaker DAC + microphone ADC | ES8311 | I2C 0x18 on SDA 47, SCL 48; I2S MCLK 18, BCLK 17, WS 15, DOUT 14, DIN 16; clocked from BCLK |
| Power manager | M5PM1 | I2C 0x6E; its GPIO2 switches the LCD rail, its GPIO3 enables the AW8737 amplifier, its GPIO0 reads the charge status (low while charging); battery voltage, USB presence and shutdown |
| Motion | BMI270 | I2C 0x68; its axes match the device frame, so no remapping |
| Keys | KEY1 GPIO 11 (TALK, the front key), KEY2 GPIO 12 (CANCEL, a side key); the other side key is the M5PM1's power button (single click powers on or resets, double click powers off, long press enters download mode) and is not read by the firmware |
The LCD rail and the amplifier are switched over I2C, not from ESP32 pins: StickS3Board (port_sticks3.cpp, drivers/sticks3.cpp) turns the rail on before the panel starts and the amplifier on only while audio plays. It is also the board's Power: battery millivolts, a percent estimated from the voltage curve (it reads high while charging), USB presence, charging, and Power off in settings through the PM1's shutdown command. The BMI270 (drivers/bmi270.cpp) needs Bosch's configuration image loaded after every reset, which takes about 8 KB of I2C writes at boot; it then gives face-down sleep (set face_down_sleep on). The IR transceiver isn't used yet.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e m5stack-sticks3 -t upload -t monitor
If the board doesn't enter download mode, connect USB and hold the power button (the side key that isn't KEY2) until the internal green LED flashes.
The StickS3 has two side keys. KEY2 is an ESP32 input and does nothing while the device is off; only the power button turns it back on after Power off.
First flash: what to check
- Boot log:
codecs: speaker ready, microphones ready (es8311 analog). Thehg.diagparts line should readdisplay st7789, microphone es8311, speaker es8311.M5PM1 initialization failedmeans the power manager didn't answer on I2C, and the screen stays dark. - Screen: the mascot is upright and not mirrored, with no stripe of noise along an edge. A one-pixel stripe means
lcd.gap_yshould be 52; an upside-down picture meanslcd.mirror_x/mirror_yinboard.cppneed flipping. - Microphone: hold KEY1 and speak; the waves move with your voice and Hermes's transcript is right.
- Speaker: replies are clear and loud enough (
set volume 80). Silence with a working microphone points at the M5PM1 amplifier enable; distorted audio, at the codec clock (codec.dac_mclk). - Console:
hermes-gadget diaganswers over the USB-C port, withimu bmi270.statusshowspowerwithbattery_mvandcharging. - Motion: lying screen up,
diagreadsmotion.znear+1000; face down near-1000; standing with the picture upright,motion.ynear+1000; with the picture's right edge up,motion.xnear+1000.
The M5PM1 sequence and the panel's window follow M5Stack's M5GFX and M5Unified StickS3 setup.
M5Stack StopWatch
Board option m5stack-stopwatch, for M5Stack's StopWatch (SKU C152): an ESP32-S3R8 with 16 MB flash and 8 MB octal PSRAM, a round 1.75" 466×466 CO5300 AMOLED over QSPI, a CST820 touchscreen, one ES8311 codec for the speaker and the MEMS microphone, an AW8737A amplifier, a blue, a yellow and a red key, and a 450 mAh battery behind an M5PM1 power manager. Neither the panel, the touch controller, the codec nor the amplifier has an ESP32 pin for power or reset: an M5IOE1 I/O expander on the same I2C bus switches and resets them. This port is experimental; see its verification status.
Back up the whole flash before the first flash. The board has no other copy of its factory firmware:
esptool.py --chip esp32s3 read_flash 0 0x1000000 stopwatch-factory.bin
Writing that file back at 0x0 restores the original firmware.
| Part | Chip | Connection |
|---|---|---|
| Display | CO5300, QSPI | CS 39, clock 40, D0–D3 41/42/46/45; 40 MHz; column offset 6; reset on the M5IOE1 (PYG5); tearing line GPIO 38, unused |
| Touch | CST820 | I2C 0x15 on SDA 47, SCL 48; reset on the M5IOE1 (PYG4); interrupt GPIO 13, unused because input is polled |
| Speaker DAC + microphone ADC | ES8311 | I2C 0x18 on the same bus; I2S MCLK 18, BCLK 17, WS 15, DOUT 21, DIN 16 |
| I/O expander | M5IOE1 | I2C 0x4F; PYG3 audio supply, PYG8 AMOLED supply, PYG4 touch reset, PYG5 panel reset, PYG10 amplifier enable, PYG9 vibration motor (kept off) |
| Power manager | M5PM1 | I2C 0x6E; cell and VIN millivolts, the charger's status on its GPIO2 (low while charging), shutdown, and the red key |
| Motion sensor | BMI270 | I2C 0x68; accelerometer only (face-down sleep) |
| Clock | RX8130CE | I2C 0x32; keeps UTC while the cell has charge |
| Keys | Blue (KEYB) GPIO 1, TALK; yellow (KEYA) GPIO 2, CANCEL; red is the M5PM1's power key |
Hold the blue key or the screen to talk, tap to answer yes, and press the yellow key or swipe down to cancel. Blue and yellow together for a second open the device settings. A short press of the red key turns the screen off and on.
The red key is the M5PM1's own: it powers the device on, a double click powers it off, and holding it enters download mode (the green LED blinks). The firmware reads it over I2C for the short press only, and turns off the single-click reset the power manager would otherwise perform. Power off in settings sends the power manager's shutdown command; on USB power the device starts again.
StopWatchBoard (port_stopwatch.cpp, drivers/stopwatch.cpp) runs the power sequence before the panel starts: both supplies on, 20 ms, the touch and panel resets low for 10 ms, and 120 ms for the CO5300 to wake. It keeps the amplifier off except while audio plays, and it is the board's Power: battery millivolts, USB presence and charging, and a percentage from the cell's measured curves: one for discharge (6 h 25 min from full to shutdown, screen on) and one for charging on USB (2 h 37 min from empty), both read by the M5PM1 on one unit. Charging shows at most 99; 100 comes when the charger rests with the cell at 4050 mV or more. A charger that rests below that is reported as still charging, so a pause is not taken for a full cell. The CST820 is told to stay awake (register 0xFE), because asleep it answers no read and its interrupt line is not used.
The microphone is quiet: speech measures 300–800 RMS per block at the usual 24 dB gain. The profile sets tap mode's speech floor to 180 (codec.vad_min_rms) instead of 500.
A tone on USB power. With USB connected and the cell nearly full, recordings carry a 10.4 kHz tone in bursts of 0.1–1 s, about as loud as speech (roughly 30% of the time once the charger tops the cell up every few seconds). On battery there is none, and none while the cell charges at full current. It is there on a laptop port and on a charger, with the charger disabled through the power manager too, and with the display still. In one test it did not change what Whisper made of speech: of six clean recordings with the tone mixed in at one and four times its level, four gave the same text word for word and two differed within Whisper's usual variation. The tone does count as speech for a detector that measures the whole band.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e m5stack-stopwatch -t upload -t monitor
The USB-C port is the ESP32-S3's own USB Serial/JTAG, so flashing and the serial console (115200) both use it. If the board doesn't enter download mode, connect USB and hold the red key until the green LED blinks.
First flash: what to check
- Boot log:
CO5300 466x466 readyandcodecs: speaker ready, microphones ready (es8311 analog).M5PM1 or M5IOE1 not foundorpower sequence failedmeans a helper chip didn't answer on I2C, and the screen stays dark.hermes-gadget diagshould list I2C devices0x15,0x18,0x32,0x4f,0x68and0x6e. - Screen: the mascot is upright inside the round glass, with the right colors. A shifted picture means the column offset of 6 is wrong.
- Touch: holding the screen records, a swipe down cancels, and taps land where you touch, also after a minute without touching.
- Keys: blue records while held, yellow cancels, blue and yellow together open settings, and a short press of red turns the screen off and on.
- Microphone and speaker: hold blue and speak; the waves move with your voice and Hermes's transcript is right. Replies are clear (
set volume 80). Silence with a working microphone points at the amplifier enable on the M5IOE1. - Power:
statusshowspowerwithbattery_mv,battery_percent,external_powerandcharging. Unplugging USB changesexternal_powerwithin a few seconds. Power off in settings turns the device off on battery. - Motion and clock: the boot log has
bmi270 ready, anddiaglistsimu bmi270andrtc rx8130. Lying screen up,motion.zreads near+1000; standing on its left edge,motion.xnear+1000; standing on its top edge,motion.ynear-1000. After the first network time the log hasRTC set from network time, and a later start takes the time from the clock chip.
Pin numbers and the M5PM1 and M5IOE1 pin functions follow M5Stack's StopWatch documentation and schematic; register addresses follow M5Stack's M5PM1 and M5IOE1 libraries. The port started from the one in allinnb/hermes-gadget-sdk. See THIRD_PARTY_NOTICES.
Spotpear ESP32-S3-1.54 muma
Board option spotpear-muma, for Spotpear's 1.54" "muma" (little wooden horse) board, SKU sp-esp32-s3-1.54-muma: an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a 240×240 ST7789 panel over SPI, one ES8311 codec for both the speaker and the microphone, a speaker, a BOOT key, a battery connector and, on the touch version, a CST816D touchscreen. It ships with the XiaoZhi firmware, whose boot log prints SKU=sp-esp32-s3-1.54-muma. This port is experimental.
Back up the whole flash before the first flash. The board has no other copy of its factory firmware:
esptool.py --chip esp32s3 read_flash 0 0x1000000 muma-factory.bin
Writing that file back at 0x0 restores the original firmware.
| Part | Chip | Connection |
|---|---|---|
| Display | ST7789, SPI | MOSI 2, SCLK 4, CS 5, DC 47, RST 38; colors inverted; backlight GPIO 42, active low |
| Speaker DAC + microphone ADC | ES8311 | I2C 0x18 on SDA 15, SCL 14; I2S MCLK 16, BCLK 9, WS 45, DOUT 8, DIN 10; amplifier enable 46 |
| Touch (touch version) | CST816D | I2C 0x15 on its own bus, SDA 11, SCL 7; RST 6, INT 12 |
| Power | GPIO 3 latches the battery path on; charge signal on GPIO 41 (high while charging); battery divider by two on GPIO 1 (ADC1 channel 0) | |
| Keys | BOOT GPIO 0 (TALK) |
The touchscreen has an I2C bus of its own, so the profile sets touch.bus and the firmware opens it on the second I2C controller. Without touch there is no CANCEL input: BOOT is the only key. Hold the screen or BOOT to talk, and swipe down to cancel.
The settings menu's Battery and power page shows the calibrated battery voltage and the charging signal. The divider ratio of two is inferred from upstream's battery table (raw 1980 to 2480 at 12 dB, about 3.1 to 4.0 V at the cell), not measured with a meter. The charge signal reads high while charging (latch_power.charging_active_high). This board has no fuel gauge; a percentage needs the opt-in estimate described under device settings.
The board reports external power while the charging signal is high or a USB host is connected to the USB-C port (latch_power.usb_external_power), and battery otherwise, so Wi-Fi modem sleep applies on battery. A USB charger without data that has finished charging counts as battery.
While the screen is dark, on battery and idle, the chip dozes: the CPU drops to 80 MHz when idle at any time, and while dozing it takes light sleep between Wi-Fi beacons, waking every 100 ms to read the keys and the touchscreen. The battery latch, the panel's control lines and the amplifier enable keep their level through light sleep. Light sleep never runs while a USB host is connected (the console and JTAG would stop), so a doze shows only on battery.
Upstream also writes 0xBB 0x38 (VCOM) to the panel; this profile keeps the ST7789 default.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e spotpear-muma -t upload -t monitor
The USB-C port is the S3's own USB Serial/JTAG, used for flashing and the serial console.
First flash: what to check
- Boot log:
battery latch enabled; calibrated voltage availableandcodecs: speaker ready, microphones ready (es8311 analog). Thehg.diagparts line should readdisplay st7789, microphone es8311, speaker es8311, with touch ready on the touch version. - Screen: the mascot is upright and not mirrored, and the colors are right (amber accents, not blue). Swapped red and blue means
lcd.bgris wrong; a negative-looking image meanslcd.invertis. - Brightness: the settings menu's brightness steps dim the screen, and 100 percent is the brightest. Reversed steps mean
lcd.backlight_invertis wrong. - Touch: holding the screen records, a swipe down cancels, and taps land where you touch.
- Microphone: hold BOOT and speak; the waves move with your voice and Hermes's transcript is right.
- Speaker: replies are clear and loud enough (
set volume 80). - Power: unplug USB with the battery in, and the device stays on. Battery and power then shows the voltage and "Not charging", and
diagreports"external_power":false; plugged into a computer it reports charging and external power. Power off in settings turns it off.
The pin map follows xiaozhi-esp32's spotpear/sp-esp32-s3-1.54-muma board at commit d91d682; see THIRD_PARTY_NOTICES.
Spotpear ESP32-S3-1.28-BOX
Board option spotpear-box128, for Spotpear's round robot, SKU sp-esp32-s3-1.28-box: an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a 1.28" 240×240 round GC9A01 panel over SPI, a CST816D touchscreen, one ES8311 codec for both the speaker and the microphone, an NS4150B amplifier, a BOOT key and a battery. It ships with the XiaoZhi firmware. Apart from the panel, it is wired like the muma. This port is experimental.
Back up the whole flash before the first flash. The board has no other copy of its factory firmware:
esptool.py --chip esp32s3 read_flash 0 0x1000000 box128-factory.bin
Writing that file back at 0x0 restores the original firmware.
| Part | Chip | Connection |
|---|---|---|
| Display | GC9A01, SPI | MOSI 2, SCLK 4, CS 5, DC 47, RST 38; 40 MHz; BGR, mirrored on X, colors inverted; backlight GPIO 42, active low |
| Speaker DAC + microphone ADC | ES8311 | I2C 0x18 on SDA 15, SCL 14; I2S MCLK 16, BCLK 9, WS 45, DOUT 8, DIN 10; amplifier enable 46 |
| Touch | CST816D | I2C 0x15 on its own bus, SDA 11, SCL 7; RST 6 |
| Power | GPIO 3 latches the battery path on; charge signal on GPIO 41 (high while charging); battery divider on GPIO 1 (ADC1 channel 0), ratio 2 | |
| Status LED | GPIO 48 | |
| Keys | BOOT GPIO 0 (TALK) |
After Espressif's default GC9A01 bring-up, the firmware writes this panel's gate timing (0x62, 0x63) and supply levels (0xC3, 0xC4), as the factory firmware does (panel_spotpear128.hpp).
The battery reading assumes the divider halves the cell voltage. At that ratio, the factory firmware's charge table, read at the same attenuation, puts a full cell near 4.0 V, but nobody has measured it on a board yet. Power off in settings lowers GPIO 3; on USB power the board stays on.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e spotpear-box128 -t upload -t monitor
The USB-C port is the S3's own USB Serial/JTAG, used for flashing and the serial console. To preview the round layout without the board, run hermes-gadget sim --board sim-240x240-round.
First flash: what to check
- Boot log:
battery latch enabled; calibrated voltage availableandcodecs: speaker ready, microphones ready (es8311 analog). Thehg.diagparts line should readdisplay gc9a01, microphone es8311, speaker es8311, with touch ready. - Screen: the mascot is upright, not mirrored, and centred in the circle, and the colors are right (amber accents, not blue). Swapped red and blue means
lcd.bgris wrong; a negative-looking image meanslcd.invertis; a mirrored picture meanslcd.mirror_xis. Faint or washed-out colors point at the register changes inpanel_spotpear128.hpp. - Brightness: the settings menu's brightness steps dim the screen, and 100 percent is the brightest. Reversed steps mean
lcd.backlight_invertis wrong. - Touch: holding the screen records, a swipe down cancels, and taps land where you touch. A swipe that reads backwards means the touch needs
touch.mirror_xortouch.mirror_y. - Microphone: hold BOOT and speak; the waves move with your voice and Hermes's transcript is right.
- Speaker: replies are clear and loud enough (
set volume 80). - Battery: with a charged cell,
hermes-gadget diagreports about 4.0 to 4.2 V. A reading far off means the divider ratio is wrong. The charging mark shows on USB and goes away on battery; if it is the wrong way round, clearlatch_power.charging_active_high. - Power: unplug USB with the battery in, and the device stays on. Power off in settings turns it off.
The pin map follows xiaozhi-esp32's spotpear/sp-esp32-s3-1.28-box board at commit d91d682; see THIRD_PARTY_NOTICES.
ESP-VoCat
Board option esp-vocat, for Espressif's ESP-VoCat AI companion kit, v1.2 only (the version is on the mainboard's silkscreen). It has an ESP32-S3-WROOM-1 module with 16 MB flash and 16 MB octal PSRAM, a round 1.85" 360×360 ST77916 panel over QSPI, a CST816S touchscreen, an ES8311 DAC driving an NS4150B 3 W amplifier, an ES7210 with two microphones, a BMI270 IMU, a BQ27220 fuel gauge, a green LED, two capacitive touch pads on its head, a microSD slot, and RST, BOOT and POWER keys. It ships with an ESP-Brookesia chatbot firmware. This port is experimental.
v1.0 boards are not supported: v1.2 moved the microphone data line (GPIO 15 to 3), the amplifier enable (4 to 15) and the LCD reset (3 to 47), and added the codec supply switch on GPIO 48.
Back up the whole flash before the first flash. The board has no other copy of its factory firmware:
esptool.py --chip esp32s3 read_flash 0 ALL vocat-factory.bin
Writing that file back at 0x0 restores the original firmware.
| Part | Chip | Connection |
|---|---|---|
| Display | ST77916, QSPI | SCLK 18, D0 46, D1 13, D2 11, D3 12, CS 14; RST 47, active high (through an inverting FET); backlight GPIO 44, active high |
| Power rails | GPIO 9 low switches the LCD/SD 3.3 V rail on; GPIO 48 high switches the codec supply on | |
| Touch | CST816S | I2C 0x15 on SDA 2, SCL 1; INT 10; no reset line |
| Speaker DAC | ES8311 | I2C 0x18; I2S MCLK 42, BCLK 40, WS 39, DOUT 41; NS4150B amplifier enable GPIO 15, active high |
| Microphone ADC | ES7210 | I2C 0x40; I2S DIN 3; microphones on MIC1 and MIC2, the speaker output looped back on MIC3 |
| Keys | BOOT GPIO 0 (TALK), under the base; RST and POWER act on the hardware only | |
| Unused by this profile | BMI270 IMU (I2C 0x68, INT1 GPIO 21), BQ27220 fuel gauge (I2C 0x55), touch pads GPIO 6 and 7, green LED GPIO 43 (active low), microSD (CLK 16, CMD 38, D0 17), UART1 on the magnetic connector (RX 4, TX 5) |
All I2C parts share one bus. GPIO 43 and 44 are UART0's pins, so the serial console is the S3's USB Serial/JTAG on the USB-C port. Hold the screen or BOOT to talk, and swipe down to cancel. The firmware doesn't read the battery or the head pads yet, and doesn't use the MIC3 loopback for echo cancellation.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e esp-vocat -t upload -t monitor
First flash: what to check
- Boot log: the
hg.lcdline readsst77916 360x360 readyafter the panel ID, and thehg.diagparts line readsdisplay st77916, microphone es7210, speaker es8311, with touch ready. - Screen: the mascot is upright, centred in the circle and not mirrored, and the colors are right (amber accents, not blue). A negative-looking image means
lcd.invertis wrong. - Brightness: the settings menu's brightness steps dim the screen, and 100 percent is the brightest.
- Touch: holding the screen records, a swipe down cancels, and taps land where you touch.
- Microphone: hold the screen and speak; the waves move with your voice and Hermes's transcript is right.
- Speaker: replies are clear and loud enough (
set volume 80).
The pin map follows Espressif's esp-bsp bsp/esp_vocat at commit f259a6a and the ESP-VoCat v1.2 schematic; the panel's start-up table comes from the same BSP. See THIRD_PARTY_NOTICES.
Elecrow CrowPanel 2.1-inch HMI
Board option crowpanel-21, for Elecrow's 2.1" round rotary display: an ESP32-S3R8 (8 MB octal PSRAM) with 16 MB flash, a 480×480 round ST7701 panel on a 16-bit RGB bus, a CST-family capacitive touchscreen, a rotary encoder with a push button, and a PCF8574 I/O expander for panel power, resets and the encoder button. This board has no microphone or speaker, so it works as a text gadget: Hermes replies, cards and prompts appear on the screen and typed messages go out through the USB console.
Unlike the SPI and i80 panels above, the ST7701 takes its initialization commands over a 3-wire SPI link and then streams pixels continuously over the 16-bit RGB bus (esp_lcd_st7701 + esp_lcd_panel_io_additions managed components).
| Part | Chip | Connection |
|---|---|---|
| Display | ST7701, 16-bit RGB | DE 40, VSYNC 7, HSYNC 15, PCLK 41 at 12 MHz; data 46/3/8/18/17/14/13/12/11/10/9/5/45/48/47/21; 480×480 round |
| Panel init | 3-wire SPI | CS 16, SCLK 2, SDA 1 |
| Backlight | PWM | GPIO 6, active-high |
| I/O expander | PCF8574 @ 0x21 | P0 touch reset, P2 touch IRQ, P3 LCD power, P4 LCD reset, P5 encoder button |
| Touch | CST826 @ 0x15 | I2C SDA 38, SCL 39; read with the CST816 report format (TouchController::Cst816) |
| Rotary encoder | A 42, B 4; button through the expander |
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e crowpanel-21 -t upload -t monitor
Or with idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/crowpanel-21/sdkconfig.defaults" build. The USB-C port is the S3's own USB Serial/JTAG, so flashing and the serial console (115200 baud) both use it.
First flash: what to check
This port is written from Elecrow's published factory example (CrowPanel repository). On the first flash:
- Boot log:
ST7701 480x480 RGB panel initialized at 12000000 Hz,touch ready, key ready, encoder ready, andparts: display st7701-rgb, ... touch yes, key yes. - Screen: the mascot is centred inside the circle and not mirrored; colours are right (amber accents, not blue). A red/blue swap means the RGB565 channel order needs flipping.
- Brightness: cycle 10 → 100 in settings; brightness must rise with the number. The backlight PWM is active-high — do not set
backlight_invert. - Touch: hold the screen and the listening waves appear; a swipe down cancels; hold the title bar one second for settings.
- Knob: each detent moves one settings item or scrolls a long reply, and the first detent wakes a dark screen; pressing the knob cancels. If the direction is reversed, swap the encoder's A and B pins in
board.cpp. - Text:
say helloover the console, or a paired Hermes, should render on the display.
Panel timings (12 MHz PCLK, 10/4/20 porches) and the ST7701 init table follow the factory RotaryScreen_2_1 Arduino example at commit faf8ecf; see THIRD_PARTY_NOTICES. Display bring-up, the brightness scale, Wi-Fi, pairing and the serial console are smoke-checked on real hardware; touch coordinates and encoder direction are not yet physically verified — see the hardware validation table.
Elecrow CrowPanel 5.0-inch HMI
Board option crowpanel-5.0, for Elecrow's 5.0" landscape display (DIS07050H): an ESP32-S3-WROOM-1-N4R8 (8 MB octal PSRAM) with 4 MB flash, an 800×480 ILI6122/ILI5960 panel on a 16-bit RGB bus, and a GT911 capacitive touchscreen. This board has no microphone or speaker, so it works as a text gadget: Hermes replies, cards and prompts appear on the screen and typed messages go out through the USB console.
Unlike the CrowPanel 2.1-inch, the ILI6122 needs no command bring-up: it is scanned out continuously over the 16-bit RGB bus through the built-in esp_lcd_rgb driver, with no PCF8574 expander and no panel-enable line. The RgbDisplay port picks this path from RgbController::Ili6122. GPIO 38 is the user GPIO_D header pin, and the firmware leaves it alone.
| Part | Chip | Connection |
|---|---|---|
| Display | ILI6122/ILI5960, 16-bit RGB | DE 40, VSYNC 41, HSYNC 39, PCLK 0 at 15 MHz; data 8/3/46/9/1/5/6/7/15/16/4/45/48/47/21/14 (B0..B4, G0..G5, R0..R4); 800×480 |
| Backlight | PWM | GPIO 2, active-high |
| Touch | GT911 @ 0x5D/0x14 | I2C SDA 19, SCL 20; INT not wired, so the driver polls (TouchController::Box3 managed GT911) |
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e crowpanel-5 -t upload -t monitor
Or with idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/crowpanel-5.0/sdkconfig.defaults" build. The USB-C port reaches the S3's UART0 through a USB-UART bridge, so flashing and the serial console (115200 baud) both use it. The S3's own USB pins, GPIO 19 and 20, carry the touch I2C instead. On the v3.0 hardware revision the board also carries a PCA9557 GPIO expander (@ 0x18) that gates touch timing; this port polls touch and does not drive that expander.
First flash: what to check
This port is written from Elecrow's published factory example (CrowPanel 5.0 repository at commit fd959ac). On the first flash:
- Boot log:
ILI6122 800x480 RGB panel initialized at 15000000 Hzandtouch ready;parts: display ili6122-rgb, ... touch yes. - Screen: the mascot renders and colours are correct (amber accents, not blue). A red/blue swap means
b.lcd.rgb.swap_red_bluein this board'sboard.cppentry needs flipping. - Brightness: cycle 10 → 100 in settings; brightness must rise with the number. The backlight is active-high — do not set
backlight_invert. - Touch: hold the screen and the listening waves appear; a swipe down cancels; hold the title bar one second for settings.
- Text:
say helloover the console, or a paired Hermes, should render on the display.
Panel timings (15 MHz PCLK, 8/4/43 and 8/4/12 porches, pclk_active_neg) and the pin map follow the factory crowpanel-esp32-5.0-3.0 Arduino example at commit fd959ac; see THIRD_PARTY_NOTICES. A boot smoke check passed on a real board: the panel initialization log, the GT911's ID, Wi-Fi and pairing. Rendering, colours, brightness and touch coordinates are not yet verified; see the hardware validation table.
Elecrow CrowPanel Advanced 10.1-inch ESP32-P4
Use board profile crowpanel-p4-101 for the Elecrow CrowPanel Advanced 10.1-inch ESP32-P4, V1.1. Elecrow identifies this panel as 1024×600; the profile is for that resolution and is based on the V1.1 documentation and schematic. The profile is experimental and builds with ESP-IDF 6.1.0 via idf.py and the dedicated CI job; this project has no ESP-IDF PlatformIO environment for P4. The PlatformIO Arduino framework listing is a different build path. The optional camera is not implemented.
| Part | Interface and profile wiring |
|---|---|
| Display | 1024×600 MIPI-DSI, EK79007 bridge, 2 lanes; PHY LDO3 at 2.5 V; backlight GPIO 31, active high; panel reset is not bonded |
| Touch | GT911; I2C0 SDA 45 / SCL 46 at 400 kHz; reset GPIO 40 active low; interrupt GPIO 42 is polled; driver probes 0x14 and 0x5D after reset |
| Microphone | PDM RX on I2S0; clock GPIO 24, data GPIO 26; 16 kHz PCM |
| Speaker output | I2S1; BCLK GPIO 22, WS GPIO 21, DATA GPIO 23; stereo, left-justified / bit-shift framing; active-low amplifier-control GPIO 30 |
| Battery / charger monitor | STC8 on I2C0 address 0x2F at 400 kHz; reads registers 0x00–0x0B |
| Wi-Fi | ESP32-C6 companion over 4-bit SDIO; CMD 19, CLK 18, D0–D3 17/16/15/14, reset GPIO 32 |
GPIO 45 and 46 are on the P4 VDD_IO_5 domain. Firmware acquires internal LDO4 at 3.3 V before creating I2C0; the DSI driver separately configures LDO3 for the DSI PHY. Touch and display initialization depend on these rails. Hardware facts are referenced from the pinned Elecrow V1.1 repository commit, including the board config.h and the V1.1 schematic files. The upstream repository has no license; only hardware facts are used here, and no Elecrow source code is copied.
Audio. The profile uses the existing Gadget audio interface: the upstream I2S microphone driver is configured for PDM on I2S0, and a P4-specific I2S1 speaker adapter handles the amplifier and stereo framing. No local microphone loopback or raw-audio diagnostic path is added.
Battery limitations. The STC8 voltage and percentage are uncalibrated estimates. The adapter exposes only the existing Gadget PowerStatus fields: battery_mv, battery_percent, and charging; a reported STC8 error leaves charging unknown. These readings do not quantify current or calibrated state of charge, and external_power remains unknown. Validate charging with a meter rather than inferring current from percentage or an LED.
Build with ESP-IDF 6.1.0 (the P4 Wi-Fi and EK79007 dependencies are pinned in main/idf_component.yml):
cd firmware/esp32
idf.py -B build/crowpanel-p4-101 \
-D IDF_TARGET=esp32p4 \
-D SDKCONFIG=build/crowpanel-p4-101/sdkconfig \
-D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/crowpanel-p4-101/sdkconfig.defaults" \
build
Releases include a merged image and an OTA app for this profile, and every CI run keeps them in its firmware-crowpanel-p4-101 artifact. To package a local build the same way:
python tools/stage_idf_build.py crowpanel-p4-101 build/crowpanel-p4-101
python tools/package_release.py --board crowpanel-p4-101 --out dist
For physical results and explicit untested items, see the CrowPanel P4 validation record. Resolution reference: Elecrow product page.
ESP32-2432S028 CYD (Cheap Yellow Display)
Board option esp32-2432s028-cyd, for the ESP32-2432S028 "Cheap Yellow Display" revision with two USB ports (micro-USB and USB-C) and an ST7789 panel. The original CYD, with only a micro-USB port, has an ILI9341 panel; this profile does not drive it. The two-USB board is a classic ESP32-WROOM-32 with 4 MB flash and no PSRAM, a 2.8" 240×320 ST7789 panel driven in landscape, the BOOT key, and an SC8002B amplifier fed by the chip's own DAC on GPIO26. The board ships with no microphone, and this profile does not use its resistive touchscreen, but if you fit a PDM MEMS microphone on the 4-pin header (IO22 carries the PDM clock, IO27 the data, SELECT tied to ground) the profile drives it: the ESP32's PDM-to-PCM converter on I2S0 turns its bitstream into the 16 kHz PCM the app records, and the amplifier lets the beeps and later replies be heard. Without a microphone it works as a text gadget: Hermes replies, cards and prompts appear on the screen and typed messages go out through the USB console. Only a two-wire PDM part fits this header — an I²S microphone such as the INMP441 or ICS-43434 needs three signal lines and does not. On boot the speaker header plays three short beeps through that DAC (port_dac.cpp), which shows the amplifier and a connected speaker work; replies are not routed there yet. It is the only classic-ESP32 profile, so the RGB, i80-parallel, DSI and codec drivers are compiled out; the panel uses the same SPI SpiDisplay path as the S3 boards, with ESP-IDF's built-in ST7789 driver.
Without PSRAM the full 320×240 framebuffer (150 KB) does not fit: about 137 KB of internal DRAM is free at boot, and Wi-Fi and the app need their share too. The port therefore holds a band of 120 rows (75 KB) instead, reserved in an early constructor before the heap fragments (port_display.cpp), and flushes through a four-row bounce buffer. The UI detects the band through Display::framebuffer_rows() and draws each band once per 120-row window, moving the window with set_frame_origin(), so the screen looks the same; a flush that times out asks the UI to repaint the whole screen, and keeps asking until a repaint reaches the panel, because the band keeps no rows to resend. For the same reason the board doesn't offer images: Hermes shows its unsupported-image notice instead, and an image.start sent anyway is refused. If Wi-Fi cannot start for lack of heap, lower kCydFrameRows in port_display.cpp.
| Part | Chip | Connection |
|---|---|---|
| Display | ST7789, SPI2 | SCLK 14, MOSI 13, MISO 12, CS 15, DC 2; no reset line (the panel resets on power-up); 320×240, swapped axes, both axes mirrored |
| Backlight | PWM | GPIO 21, active-high |
| Speaker | SC8002B amplifier | the chip's own DAC, channel 1 on GPIO 26; the speaker connects to the board's two-pin header |
| Microphone | PDM MEMS (optional, not fitted) | I2S0: PDM clock on GPIO 22, data on GPIO 27, on the 4-pin header |
| Button | BOOT | GPIO 0 (TALK) |
The board also carries a resistive XPT2046 touchscreen on its own pins (CLK 25, MOSI 32, MISO 39, CS 33, IRQ 36), a microSD slot on VSPI (SS 5, SCK 18, MISO 19, MOSI 23), an RGB LED on GPIO 4, 16 and 17 and a light sensor on GPIO 34; this profile does not use them. The amplifier plays the three boot beeps only, and the microphone header is wired for a PDM part but the stock board has none fitted, so a recording without one captures silence. Probe your own board before assuming it: the CYD ships in several revisions whose backlight pin, panel controller and colour order differ.
Build and flash it with PlatformIO:
cd firmware/esp32
pio run -e esp32-2432s028-cyd -t upload -t monitor
Or with idf.py set-target esp32 followed by idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32-2432s028-cyd/sdkconfig.defaults" build. The micro-USB port reaches UART0 through a USB-UART bridge (usually CH340), so flashing and the serial console (115200 baud) both use it.
First flash: what to check
The pin map comes from the community ESP32-Cheap-Yellow-Display reference (PINS.md, and DisplayConfig/CYD2USB/User_Setup.h for the two-USB revision's ST7789). The contributor ran an earlier build of this port on a Guition ESP32-2432S028: its display (in monochrome), the DAC speaker, and Wi-Fi and pairing set with menuconfig worked. Touch was off and no microphone was fitted. The merged profile draws in colour through the banded framebuffer and has not run on a board yet, so the colour order, inversion and mirroring are the contributor's settings and still unchecked. On the first flash:
- Boot log:
st7789 320x240 readyand theparts:line naming the display, the microphone (pdmonce a PDM mic is fitted,nonewithout one) and no touch. - Sound: about a second into boot the speaker header plays three short beeps, and the log shows
three beeps on GPIO26 (DAC channel 1). Silence points at the amplifier wiring or the speaker, not the panel; a log line about GPIO26 not being a DAC output meansb.speaker_dacinboard.cppis wrong. - Memory: no
the reserved 120-row band does not fiterror, anddiagreports a plausible free heap. The band is reserved before Wi-Fi starts, so a Wi-Fi failure to allocate is the signal to lowerkCydFrameRows. - Screen: the mascot renders in landscape and colours are right (amber accents, not blue). A red/blue swap means
b.lcd.bgrin this board'sboard.cppentry needs flipping; an inverted picture meansb.lcd.invertdoes. - Brightness: cycle 10 → 100 in settings; brightness must rise with the number. The backlight is active-high — do not set
backlight_invert. - Orientation: the picture should not be mirrored or upside down; adjust
b.lcd.swap_xy,mirror_xandmirror_yif it is. - Button and microphone: holding BOOT records a voice turn. With a PDM mic on the header the log shows
microphone ready (pdm)and speaking into it shows in the level meter;microphone did not start: not enough internal RAM for its buffersmeans the I2S0 DMA did not fit beside the framebuffer band, so lowerkCydFrameRows. Without a microphone the recording is silent and replies are text only. - Text:
say helloover the console should render on the display.
Only hardware facts (pin numbers and panel settings) come from that reference; no code is copied. The firmware builds, but it has not been run on a board and has no physical report; see the verification table.
Waveshare ESP32-P4-WIFI6-Touch-LCD-3.4C
Board option ws-p4-touch-lcd-3.4c, for Waveshare's ESP32-P4-WIFI6-Touch-LCD-3.4C (SKU 31523): a round 800x800 IPS panel on a MIPI-DSI bus (JD9365 controller), GT911 capacitive touch, ES8311 speaker codec plus ES7210 microphone ADC, and an ESP32-C6 companion for Wi-Fi 6 over a 4-bit SDIO link.
| Part | Chip | Connection |
|---|---|---|
| Display | JD9365, 800x800 MIPI-DSI | 2 data lanes @ 1500 Mbps, DPI clock 80 MHz, RGB565; DSI PHY from internal LDO channel 3 @ 2500 mV |
| Backlight | PWM | GPIO 26, active-high |
| Touch | GT911 | I2C SDA 7, SCL 8 (port 1), reset/int not bonded |
| Microphone | ES7210 ADC (dual mic) | I2S MCLK 13, BCLK 12, WS 10, DIN 11 |
| Speaker | ES8311 codec + amp | I2S DOUT 9; amplifier enable GPIO 53 (active high) |
| Wi-Fi / BLE | ESP32-C6 companion | standard P4 function-board SDIO pins |
| MicroSD | SDIO 3.0 slot, 4-bit | CLK 43, CMD 44, D0–D3 39–42 (Waveshare XC pinout) |
| LCD reset | GPIO 27 |
The microSD slot is FAT32 only; the firmware never formats a card. With set sd_log on, the device log is copied to hermes.log on the card (rotating past 512 KB to hermes.log.1), including when the card is inserted after boot. The slot is SDMMC slot 0; slot 1 carries the C6 companion's SDIO link and stays with it.
Build with idf.py (no PlatformIO env):
cd firmware/esp32
idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/ws-p4-touch-lcd-3.4c/sdkconfig.defaults" \
set-target esp32p4 build
Releases don't include this board yet, so the browser installer doesn't list it. CI builds the profile on every change.
Experimental. The owner confirmed the display, C6-hosted Wi-Fi, pairing, reconnect after restart, factory reset and a one-hour run; touch coordinates, the microphone, the speaker, network recovery and OTA are not verified. See the partial physical report.
Wi-Fi caveat: the ESP32-C6 companion on this board does not ship with an esp_hosted slave image that this host (esp_hosted 2.12.6) can talk to. g_wifi.begin() times out after about 10 s and the gadget runs offline until the C6 is flashed. Flash network_adapter.bin (CrowPanel C6 firmware, V2.12.3, in CrowPanel_Advance_ESP32-P4 Display_Firmware_Upgrade_Guide/.../) to the C6 through its SH1.0 UART header with esptool before expecting Wi-Fi. The report lists every step that was needed.
Waveshare ESP32-P4-WIFI6-Touch-LCD-7B
Board option ws-p4-touch-lcd-7b, for Waveshare's ESP32-P4-WIFI6-Touch-LCD-7B (SKU 32510): a 1024x600 MIPI-DSI panel using EK79007, GT911 capacitive touch, ES8311 speaker codec plus ES7210 microphone ADC, and ESP32-C6 Wi-Fi over 4-bit SDIO. Hardware pins and display timings follow Waveshare's BSP component 3.0.1; the board configuration targets the ESP32-P4 rev 3 silicon family and 32 MiB flash observed on the connected device.
| Part | Chip | Connection |
|---|---|---|
| Display | EK79007, 1024x600 MIPI-DSI | 2 data lanes @ 1000 Mbps; DPI 52 MHz; H: 10/160/160, V: 1/23/12; DSI PHY internal LDO channel 3 @ 2500 mV; software 180° X/Y framebuffer transform |
| Backlight | PWM | GPIO 32, inverted output |
| Touch | GT911 | I2C SDA 7, SCL 8; reset and interrupt not connected; polling; axes unmirrored to match the software-rotated display |
| Microphone | ES7210 ADC (dual mic) | I2S MCLK 13, BCLK 12, WS 10, DIN 11 |
| Speaker | ES8311 codec + amp | I2S DOUT 9; amplifier enable GPIO 53 (active high) |
| Wi-Fi / BLE | ESP32-C6 companion | SDIO CMD 19, CLK 18, D0-D3 14-17; reset GPIO 54 (active high) |
| Camera | Optional OV5647 | Two-lane MIPI-CSI; SCCB shares I2C SDA 7/SCL 8; vendor preview example assigns no separate reset/PWDN GPIO |
| LCD reset | GPIO 33 | |
| Console | USB-to-UART bridge | UART0, 115200 baud; USB Serial/JTAG remains secondary |
On camera-equipped 7B units, the firmware exposes camera.capture. It captures an OV5647 still, reduces it to 640×512 RGB565 for the existing generic action result, and returns format, width, height, and image_b64 in the existing action result; see Device actions. The plugin saves it as a timestamped PNG under ~/.hermes/gadgetpix/ and returns the file's path, not the image. This reuses the current action/result message types; no new protocol messages are added. SKU 32510 is the standard version without the bundled camera; an OV5647 module is required. The camera connector and SCCB wiring follow Waveshare's camera preview example at commit 9fcd49a8c927a00f5583c22d568b3448addbe51c; no vendor source code is copied. Two device captures were completed on the attached camera module. In the integrated development test, the plugin saved the latest result as a valid 640×512 PNG; its image content and quality were not visually reviewed, and broader physical validation remains incomplete. See hardware validation.
Build with ESP-IDF 6.1.0 (the project's P4 CI toolchain) and the board defaults:
cd firmware/esp32
idf.py -B build/ws-p4-touch-lcd-7b \
-D SDKCONFIG=build/ws-p4-touch-lcd-7b/sdkconfig \
-D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/ws-p4-touch-lcd-7b/sdkconfig.defaults" \
set-target esp32p4 build
idf.py -B build/ws-p4-touch-lcd-7b \
-D SDKCONFIG=build/ws-p4-touch-lcd-7b/sdkconfig \
-D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/ws-p4-touch-lcd-7b/sdkconfig.defaults" \
-p <PORT> flash monitor
This is an experimental profile. Touch input/coordinates, actual microphone capture, audible speaker output, Wi-Fi loss/recovery, OTA and the full physical checklist remain unverified.
Build and flash
No toolchain needed: the browser installer flashes each release's prebuilt firmware from Chrome or Edge, then sets up Wi-Fi and pairing. The release files are also on the releases page, for esptool.py write_flash 0x0 hermes-gadget-<board>-<version>.bin, which also erases the board's settings.
To build it yourself, with ESP-IDF 5.3 or later installed (. $IDF_PATH/export.sh):
cd firmware/esp32
idf.py set-target esp32s3
idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/esp32s3-breadboard/sdkconfig.defaults" build
idf.py -p COM5 flash monitor
Or with PlatformIO, which downloads ESP-IDF itself:
cd firmware/esp32
pio run -e esp32s3-breadboard -t upload -t monitor
The firmware is written for ESP-IDF 5.3 and later. It builds with ESP-IDF 6.1 through PlatformIO:
- ESP32-S3 breadboard: app image 1.13 MB in a 1.94 MB app slot, 14% of static RAM;
- ESP32-S3-Touch-AMOLED-1.75: 1.12 MB, otherwise the same;
- classic ESP32 with custom pins.
The flash holds two app slots (partitions.csv), so later firmware can arrive over the air, and a 56 KB coredump partition in the space before them for the last crash. A board flashed with an earlier release gets the new partition table with its next USB flash. NVS stays where it was, so its settings and device key survive.
Updates over the air
Once a board runs this firmware, new firmware can reach it over Wi-Fi. On the Hermes host:
hermes gadget update "Kitchen" --latest # the newest release's firmware for Kitchen's board
hermes gadget update "Kitchen" firmware/esp32/.pio/build/esp32s3-touch-amoled-175/firmware.bin
--latestreads the newest release's manifest, picks the image for the device's board, and checks its size and SHA-256 against the manifest before using it. A device that already runs that version or a newer one, including a source build such as0.4.0-12-gabc1234, is left alone, and a device whose version can't be read is refused;--forceinstalls the release anyway.hermes gadget devicesshows the version each device runs.- The gateway installs the image as soon as the device is online, and the command waits and reports progress (
--no-waitreturns at once). - The device shows the progress, restarts into the new firmware, and keeps it once it reaches Hermes again.
- If the new firmware doesn't reach Hermes within 5 minutes, or crashes before then, the device goes back to the previous one by itself.
- Only the Hermes that enrolled the device can update it: every image is authorized with the device's own key. The command also refuses an image built for another board.
- The dev server takes the same images:
update <path>in its console.
On Windows, keep the project on a short path such as C:\src\hermes-gadget-sdk. ESP-IDF's linker-script step can exceed the Windows command-line length limit when the build directory is deeply nested.
idf.py menuconfig → Hermes Gadget sets the board, default Wi-Fi, server URL and device name. All of them can also be changed at run time over serial.
Serial console
Open the console at 115200 baud (idf.py monitor, pio device monitor, or hermes-gadget console --port COM5). It shares its command set with the simulator:
gadget> set wifi_ssid MyWifi
@ok wifi_ssid
gadget> set wifi_pass secret
@ok wifi_pass
gadget> set server ws://192.168.1.20:8765/gadget
@ok server
gadget> status
@status {"device_id":"hg-...","phase":"online","screen":"pairing","pairing_code":"ABCD2345",...}
A device refused for a gateway route has "unpaired_reason": "routed" in status (see Hermes integration). When the board has a power adapter, status includes a power object; the state sensor message mirrors its battery fields. On the CrowPanel P4, the STC8 adapter samples its 12-byte record every 5 seconds through the app power poller and maps it to the existing Gadget fields battery_mv, battery_percent, and charging. The adapter does not expose raw registers, battery-state enums, battery_present, or external_power.
| Command | Meaning |
|---|---|
status |
JSON status |
diag |
JSON diagnostics: build, reset reason, memory, Wi-Fi, which parts came up, I2C addresses that answer, task stacks, connection |
diag log |
The last few KB of log lines, kept in RAM since boot |
get <key> |
Read a setting (secrets are masked) |
set <key> <value> |
Write a setting; an empty value clears it |
say <text> |
Send a typed message |
talk / release |
Press or release TALK (bench automation) |
cancel |
Press CANCEL |
new-session |
Start a fresh conversation (same as holding CANCEL for 2 s) |
settings / settings close |
Open or close the local settings and hardware checks |
wifi-setup / wifi-setup close |
Start or cancel phone setup; the start response includes temporary network credentials |
wifi / wifi list |
The saved Wi-Fi networks as @wifi JSON, without passwords |
wifi add <ssid> [password] |
Save a network without joining it; leave out the password for an open network |
wifi join <ssid> |
Move a saved network first and join it now |
wifi forget <ssid> |
Remove a saved network |
phone / phone pair / phone pair close / phone forget |
On boards with Bluetooth: phone app state, open or close pairing, or remove every paired phone (protocol) |
perf / perf on / perf off / perf bench |
Frame timing and the renderer bench (measure frame timing) |
face / face <expression> [seconds] |
Report the face's expression as @face JSON, or set it: neutral, happy, confused, alert or sleepy, for 1 to 3600 seconds or until the next turn |
yes / no |
Answer the question on screen |
reconnect |
Drop and re-open the Hermes connection |
forget-key |
New device identity on next boot (re-enrollment and re-pairing) |
factory-reset |
Erase the device key and all settings |
The keys are name, server, token, talk_mode (hold or tap), touch_talk (on or off; touchscreens with a TALK button, see Touch to talk), volume, brightness, screen_timeout (0..3600 seconds, 0 disables it), clock (0 or 5..3600 seconds of rest before the resting clock shows; 0, the default, turns it off), time_format (12h or 24h, the clock face), timezone (a POSIX TZ string such as CET-1CEST,M3.5.0,M10.5.0/3; the default UTC0; ESP32 boards), battery_display (icon, percentage, both or off), wifi_deep_sleep (on, the default, or off; see Deep Wi-Fi sleep), animation (on, the default, or off; see Animation), sd_log (on or off, off by default; boards with a microSD slot, see SD card logging), language (en, es, or auto to follow Hermes; see Language), wifi_ssid and wifi_pass. Firmware built with tailnet support adds tailnet (on or off) and ts_key (a Tailscale auth key; get shows <set>). The device settings menu saves volume, brightness, talk mode, touch to talk, battery indicator, screen timeout, clock face and language without a console.
In the diag report, i2c lists the addresses that answered, such as 0x18. A probe can time out while another task uses the bus, so the scan tries each address up to three times. An address that times out on every try appears as timeout at 0x19, and the scan continues. Four such addresses in a row end the scan with bus stuck at the first of them, such as bus stuck at 0x08. That usually means a device or a short holds SDA or SCL low.
Saved Wi-Fi networks
The device keeps up to five Wi-Fi networks and joins whichever is in range, so it can move between home, an office and a phone hotspot without new setup:
gadget> wifi add "Home Wi-Fi" "correct horse"
@ok wifi add
gadget> wifi add Phone hotspot-pass
@ok wifi add
gadget> wifi
@wifi {"networks":[{"ssid":"Home Wi-Fi","tested":true,"open":false},{"ssid":"Phone","tested":false,"open":false}],"max":5,"current":"Home Wi-Fi"}
- Put a name or password with spaces in double quotes. Inside quotes,
\"is a quote and\\a backslash. - The list is in order: the network that last worked comes first and is tried first at startup.
testedturns true once the device has joined the network with its saved password. Saving a new password for a network clears it again.wifi adddoes not check the password, so a network saved out of range showsfalseuntil the device first joins it.- When the link drops, the device retries the same network once. If that fails too, it scans and joins the first network if the scan saw it, else the strongest saved network it saw. A network that failed twice is passed over while another saved one is in range. When the scan finds no saved network, for example because it is hidden, the device tries the next one in the list. With one saved network it never scans and retries as before.
set wifi_ssidandset wifi_passwork on the first network: setting a new name saves that network first and keeps the others. If five are saved, the last one is dropped. An emptywifi_ssidforgets the first network. Phone setup saves its network first the same way.factory-resetforgets every network, and the access point it last joined.
Machine-readable lines start with @, so tools can drive a bench device. hermes-gadget provision is a thin wrapper over these commands.
Wi-Fi reconnect
A join that names no access point first scans every channel. To skip that, the device records the access point it joined after each good connection: its BSSID, its channel and the DHCP lease (key wifi_fast, written only when something changed).
- At boot and after the link drops, the first attempt on the same network aims at that access point on that channel, with no scan.
- If that attempt fails, for example because the router moved to another channel or the device is somewhere else, the device joins normally at once: the usual scan and retries in saved Wi-Fi networks. The failed fast attempt doesn't count against the network or lengthen the battery backoff. The next good join replaces the record.
- DHCP asks for the last address first (
CONFIG_LWIP_DHCP_RESTORE_LAST_IP, on for every board), which skips the discovery round when the router still has the lease. - Static address (opt-in): with
CONFIG_HG_WIFI_REUSE_IP(menuconfig, Hermes Gadget), a fast join reuses the last lease as a static address and skips DHCP. Turn it on only when the router reserves that address for the device. Nothing renews the lease, and an address the router gave to someone else in the meantime conflicts. Every other join uses DHCP. - Forgetting a network forgets its record.
How long a reconnect takes has not been measured on hardware for this firmware.
Power-on sequence
- Boot: about 1 s.
- Wi-Fi: the first saved network, else the one from menuconfig. Without credentials the device opens a temporary network for phone setup.
- Connect: the device opens the WebSocket to
server, retrying 1 → 30 s with backoff. - Authenticate: it enrolls its key on first contact and proves it with an HMAC afterwards.
- Pair or ready: an unpaired device shows a pairing code (approve with
hermes gadget pair); a paired one goes to Ready.
Known limits of the reference firmware
- Push-to-talk or tap with energy VAD. There is no wake word; the protocol leaves room for one (
audio.start.mode). - Wi-Fi setup works over USB or a temporary password-protected network. A Bluetooth link for a phone app exists, but no board enables it yet: each board turns it on after it passes the Bluetooth checks. There is no phone app in this repository.
- Firmware updates are authorized with the device key, but images aren't signed: the bootloader runs whatever a trusted Hermes installs. Secure Boot isn't enabled.
- Keyboard entry is ASCII. Replies use the shared font (ASCII, Latin-1 and the Russian alphabet); the plugin folds other characters to what it draws.
M5Stack Cardputer ADV
Experimental profile cardputer-adv, for K132-Adv with Stamp-S3A only.
The original Cardputer and Cardputer v1.1 have different audio and keyboards.
ESP32-S3FN8 provides 8 MB flash and no PSRAM. SD is not required: firmware,
Wi-Fi configuration and pairing identity live in internal flash/NVS.
| Peripheral | Wiring |
|---|---|
| ST7789V2, landscape 240x135 | MOSI 35, SCLK 36, CS 37, DC 34, reset 33, backlight 38 |
| Shared I2C | SDA 8, SCL 9; ES8311 at 0x18, TCA8418 at 0x34 |
| ES8311 duplex I2S | BCLK 41, LRCLK 43, speaker data 42, microphone data 46; no MCLK wire |
| TCA8418 keyboard | Interrupt GPIO11; 7x8 scan matrix mapped to the 4x14 printed layout |
| G0 / BOOT | GPIO0, active low |
| Battery sense | GPIO10, divider ratio 2; voltage only |
The ES8311 derives its clock from BCLK. The existing Gadget codec driver owns both directions; the microphone and speaker share the codec. No amplifier control GPIO is assigned; the headphone jack disables the speaker in hardware. The BMI270, SD slot, RGB LED and IR are left unused.
Build and first flash
cd firmware/esp32
pio run -e cardputer-adv -j 1
Before the first install, read and keep a complete 8 MB flash backup with esptool. Keep it private: it can contain settings from the previous firmware. For recovery hold G0 while connecting USB with the power switch OFF, as in M5Stack's download-mode instructions.
esptool --chip esp32s3 --port /dev/ttyACM0 read-flash 0 ALL original-cardputer-adv.bin
pio run -e cardputer-adv -t upload --upload-port /dev/ttyACM0
The initial install replaces the previous bootloader and partition table, including an existing launcher. Restore the complete backup at address 0 to return to the previous installation. This profile uses Gadget's normal two application slots and rollback behavior; it does not preserve M5Launcher.
Configure Wi-Fi and the Hermes URL over the USB serial console, or through phone setup, then approve pairing on the Hermes server. The USB console runs through the S3's native Serial/JTAG port, not the UART pins used by audio.
Enter Wi-Fi from a phone
The network name and password shown on the setup screen belong to the Cardputer's temporary access point. They are not fields to fill with its keyboard.
- Open the phone's Wi-Fi settings and join that temporary network with the password currently displayed on the Cardputer. Stay connected if the phone warns that the network has no internet.
- Open
http://192.168.4.1in the phone's browser. - Enter your home 2.4 GHz Wi-Fi name and password. Keep the Hermes URL already provisioned, or enter the server's Gadget URL.
- Choose Check connection and save. When it succeeds, reconnect the phone to its usual Wi-Fi and approve the Cardputer's pairing code on Hermes.
The temporary network expires after ten minutes. To reopen it, press Tab on the
Cardputer, navigate with Fn+; / Fn+. to Wi-Fi setup, and select with Enter.
USB console command wifi-setup opens it too. Each setup session has a new
password; use the current one shown on the display.
The keyboard editor in this profile sends chat messages after connection. Wi-Fi credentials are entered on the phone page or provisioned over USB.
Controls
| Control | Action |
|---|---|
| Hold G0, speak, release | Voice request; tap selects in settings or answers a prompt |
| Type, then Enter | Open local editor and send a text message (up to 256 ASCII characters) |
| Shift + character | Uppercase or printed symbol |
| Backspace | Delete the last draft character |
| Fn + Esc (the backtick key) | Discard draft, cancel recording/reply, or go Back |
| Fn + ; / Fn + . | Scroll up / down; navigate settings |
| Tab or Fn + Enter | Open settings |
| Enter in settings or a prompt | Select / confirm |
| Fn + P | Next configured Hermes profile |
| Fn + Z | Screen off/on; Wi-Fi stays connected |
The editor is local to this board port. It neither sends unfinished text nor executes typed console commands. Typing is enabled on Ready and reply screens while online and idle. A network loss, incoming prompt, alarm, update or active voice turn closes the editor and clears the draft. The first keyboard press on a dark screen only wakes it. The normal Gadget display returns after sending or discarding a draft.
Sources and verification
Hardware facts: M5Stack K132-Adv product page and schematic, M5Cardputer bf64d317 (key layout and TCA8418 scan mapping), M5Unified 96576a14 (audio clock source and battery divider), and M5GFX 28d47949 (panel geometry). No vendor implementation is copied.
USB smoke testing on a connected K132-Adv / Stamp-S3A identified ESP32-S3 rev
v0.2, 8 MB flash and no PSRAM. The PCB revision was not recorded. The initial
checks below used firmware built from upstream 7e18943 (0.5.0) plus this
Cardputer port, including its display-initialization guard. The later OTA report
uses the rebased port and a Cardputer-specific receive-buffer fix. Installation
checksum verification passed.
Firmware 0.5.0 booted and reported ST7789 240x135, ES8311 microphone and speaker,
and a ready TCA8418; I2C probes found 0x18, 0x34 and 0x69. Initial diagnostics
reported 84,764 bytes free internal RAM (largest block 43,008 bytes). The saved
server URL and device identity remained present after about 11.7 hours powered
on. The owner reports seeing the Wi-Fi setup information on the display.
On 2026-11-07, USB provisioning joined the owner's home Wi-Fi (reported RSSI
-54 dBm), reached the existing Hermes Gadget gateway and completed pairing.
The device's own diagnostics confirmed online, paired. The server's
built-in hermes pairing approve gadget <request-id> command approved the
request identified as this Cardputer.
The owner subsequently confirmed that keyboard/text entry and the G0 voice request/response flow work on this installed firmware. The owner also confirmed that Wi-Fi settings survive switching the device off and on. These are owner-reported functional checks, not instrumented audio-quality measurements or an exhaustive test of every key and shortcut. The owner also confirmed that the device remains usable after switching it off and on without another pairing approval; subsequent USB diagnostics confirmed it was still paired.
The owner also confirmed readable text, correct display orientation and no visible cropping or color problems; text and voice requests with USB disconnected and the device powered by its battery; and screen off/on with Fn+Z followed by successful requests. This verifies basic battery operation, not battery endurance or a full discharge curve. Network-loss recovery testing was explicitly skipped at the owner's request and remains unverified.
Phone provisioning, battery endurance and the rest of the physical checklist remain pending; retain experimental status. See the OTA report below for the separate update and recovery checks. Host tests cover key event decoding, modifiers, invalid FIFO events, bounded text entry and restoring the normal UI after editing. See the physical checklist.
OTA and rollback report
Tested on 2026-11-07 on the same K132-Adv / Stamp-S3A, powered by USB and
connected to the existing Hermes gateway over Wi-Fi. The host retained a full
8 MB backup privately before testing. The source was the port at f7ef488,
based on upstream 648fbde, plus the Cardputer-only OTA receive fix in
port_events.cpp. Firmware reports 0.5.0-cadv-ota-f7ef488; that version label
identifies the base and is shared by the working and deliberately faulty test
variants. Their ELF hashes distinguish the actual images.
- Reproduced failure: two OTA attempts from the original installed 0.5.0
failed with
sequence: a chunk of the image went missing. USB logs showedout of memory for a 4100 byte event; one attempt used passive USB logging without diagnostic polling. The existing firmware kept running. The sender's 64 KB window could exhaust internal RAM while the app task wrote to flash. - Fix: only on
CONFIG_HG_BOARD_CARDPUTER_ADV, the ESP32 event bridge limits outstanding firmware events to four, including the event being processed. With the sender's 4 KB chunks this holds about 16 KB of queued payload. The receive task waits for a slot, applying TCP backpressure; all allocation, queue-failure and event-release paths return their slot. Waiting is bounded to two seconds. The portable core and wire protocol are unchanged. - Bootstrap: the fix was first installed over USB as an app-only write at
0x20000, with flash hash verification. NVS, the partition table and OTA data were not rewritten. The same identity, Wi-Fi and pairing remained usable. - Successful OTA: the corrected working image (1,601,616 bytes) then
installed over Wi-Fi from
ota_0intoota_1. After reboot, diagnostics identified ELF hash prefixc5e63ff93ed374ba, online and paired, withprobation: false; the log reportedkept the new firmware. - Rollback: a second OTA installed a local variant in
ota_0whoseWsTransport::connectloggedTEST ONLYand returned without connecting. Diagnostics identified the fault variant's ELF prefix06879bf9648b52aa, Wi-Fi joined, Hermes connecting andprobation: true. At uptime 300,372 ms (five minutes after its updater started at 372 ms), the unmodified updater logged that it was going back and rebooted without manual intervention. Diagnostics then identified the working ELFc5e63ff93ed374bainota_1, online and paired, withprobation: false. Device identity, saved server and Wi-Fi matched the pre-test state. No access-point or gateway outage was used.
The working app's SHA-256 is
7d3b2fc9ee15b6cf3a0322132c9e09acad07407eef1c2e884e070664d9ab9a7f.
The fault-injection image's SHA-256 is
1d2a186af3bac48210ad5fce17b4b1f778cd5e6ed040c29d3d63589923c8b150.
The temporary fault injection is not part of the board profile or release
sources. These checks do not establish battery endurance, network-loss recovery
or complete physical verification.
Cardputer ADV review build recheck
Following the maintainer's review, firmware sources at ed4f99e inherit the
shared platform = espressif32 instead of pinning a board-specific platform.
A clean pio run -e cardputer-adv -t clean followed by
pio run -e cardputer-adv -j 2 succeeded with the resolved platform 8.0.0 and
ESP-IDF 6.1.0. The standard build reports version 0.5.0, with no temporary
configuration or version override. Static RAM is 54,464 bytes; the application
uses 1,601,199 of 2,031,616 slot bytes (21% headroom).
The 1,601,616-byte app was installed by OTA on the same Cardputer on 2026-11-07.
After reboot, live diagnostics identified ELF prefix 5718545567a38d7e in
ota_0, online and paired, Wi-Fi joined, and probation: false; the log reported
kept the new firmware. ST7789, ES8311 microphone/speaker and the keyboard were
initialized. The device identity and connection settings were retained.
After this exact build was installed, the owner confirmed on 2026-11-07 that the display is readable and correctly oriented, physical keyboard entry with Backspace and Enter sends text successfully, and a G0 voice request captures speech and receives an audible spoken reply. These are owner-reported physical functional checks, separate from initialization diagnostics and host tests; they do not establish exhaustive key coverage or measured audio quality.
App SHA-256:
979946abc4ed68fa18efcf6ffb0236196b9e4c855f4195e7419fa768c281603a.
The earlier reports retain their original firmware identities; the board stays
experimental while the remaining full-checklist items are unverified.
Cardputer ADV receive ownership follow-up
Review found that waiting for an OTA receive slot must not keep a borrowed pointer into the transport's shared reassembly buffer. The SDK uses a separate event loop for each WebSocket client, while closing the old client runs on the send task, so callbacks from a replacement client can overlap that wait.
The Cardputer receive path now detaches a completed message into local owned storage before posting it. The payload remains valid throughout admission, and returning from the old callback does not clear a replacement client's partial frame. Host regression tests reuse/reallocate the shared buffer during delivery and exercise both successful and refused admission, including binary short frames. This protects the newly introduced waiting interval; it is not a claim that every pre-existing transport reconnect path was redesigned.
These follow-up changes are checked in host tests and an ESP32 build only. The physical reports above describe their recorded images. The device now runs M5Launcher for separate experiments, so this newer Hermes receive change has not yet been installed or physically tested.