Firmware for an ESP32-S3 (or, untested so far, an ESP32-S2 or ESP32-P4) strapped to one thingino camera, which makes that camera flashable and debuggable over the network with nothing else attached:
- Flashing. The thingino-dfu daemon (
dfu-remote) runs on the unit, with the camera's USB port on the ESP32-S3's USB host.thingino-dfu --hostand the web flasher's remote mode talk to it as they would to a Linux host: detect, bootstrap, read, write, verify. - Serial console. The camera's UART over TCP, raw and as RFC 2217.
- Power and boot pin. The unit switches the camera's power and holds its boot pin, so it can put the camera into the bootrom on request and power-cycle one that stopped answering on USB.
- Flash chip. With a SOIC-8 clip on the camera's flash, the unit is a flash programmer for flashrom, for a camera that no longer boots far enough to be flashed over USB.
- Findable like a camera. A thingino-style Wi-Fi setup portal on first boot, then mDNS
_thingino._tcpand a status page, which the thingino app lists and opens. - Part of a bench. The hardware-development-lab relay panel finds units on its network and drives them next to its relay boards: see On a bench panel.
Nothing is stored on the unit: the client sends the loader pair with each bootstrap, and images stream through it, so the default build runs without PSRAM.
| Chip | Build | Network | Camera USB | Status |
|---|---|---|---|---|
| ESP32-S3 | ./image.sh, or ./image.sh psram |
Wi-Fi | full speed | in use |
| ESP32-S2 | ./image.sh s2 |
Wi-Fi | full speed | builds, untested |
| ESP32-P4 | ./image.sh p4 |
Ethernet | high speed | builds, untested |
- ESP32-S3: the build needs no PSRAM and runs on every S3 module.
./image.sh psrammakes one that also puts octal PSRAM (N8R8, N16R8) to use; nothing needs it yet, so releases leave it out. - ESP32-S2: one core and 320 KB of SRAM, which does not hold a bootstrap next to Wi-Fi, so the build is for modules with PSRAM (quad, like the 2 MB of an S2FN4R2). On boards whose only USB port is the native one, that port is the camera's.
- ESP32-P4: no radio, so the unit is on Ethernet: the chip's EMAC with an IP101 PHY on
ESP-IDF's P4 default pins, which are those of Espressif's P4 Function EV board
(
src/eth.rs). Addresses come by DHCPv4 and SLAAC, there is no setup portal, and the hostname isthingino-backpack-xxxxfrom the Ethernet MAC. The camera's USB goes to the high-speed port. The camera's power, boot pin and UART are on GPIO20 to 23, picked without a particular board in mind. ESP-IDF 5.5 builds for P4 silicon 3.1 and later;sdkconfig.esp32p4says what earlier chips need.
| ESP32-S3, -S2 | ESP32-P4 | Camera |
|---|---|---|
| GPIO4 | GPIO20 | Power switch (a MOSFET module or similar): high = camera on |
| GPIO9 | GPIO21 | Flash DI, pin 5 of an SOIC-8 NOR flash (open-drain: low = boot from USB) |
| GPIO6 | GPIO48 | SoC BOOTSEL, on boards that bring it out (see below) |
| GPIO1 (TX) | GPIO22 (TX) | UART RX |
| GPIO2 (RX) | GPIO23 (RX) | UART TX |
| GPIO19, GPIO20 | the high-speed port's own | USB D-, D+ |
| GND | GND | GND |
- The S2 and S3 share every pin but the flash's HOLD, and GPIO1 to 9 are on the edge pins of the common boards: DevKitC-style boards, every XIAO ESP32S3 (GPIO1 to 6 are D0 to D5, GPIO7 to 9 are D8 to D10), and the S3 Super Mini, Waveshare ESP32-S3-Zero and S2 Mini, which label their pins with GPIO numbers.
- GPIO19 and GPIO20 are the only pins the S2's and S3's USB PHY reaches. On a XIAO, a Super Mini, an S3-Zero or an S2 Mini they go only to the USB-C port, which is then the camera's: the board runs from its 5V pin (VBUS on the S2 Mini), and reflashing it means holding BOOT while plugging it into the computer. The P4's high-speed port has D- and D+ pins of its own, which are not GPIOs.
- Some DevKitC-style boards have a solder jumper on the back labeled USB-OTG, which connects the native USB port's VBUS to the board's 5 V. Whether it needs closing depends on the board and on how the camera is hooked up: a camera on that port that gets no VBUS may not enumerate.
- On a XIAO ESP32S3 Sense, GPIO7 to 9 are shared with the expansion board's SD card slot, which has to stay empty.
- The P4's power, boot and UART pins were picked without a particular board in mind: move
them in
src/main.rsif the board needs those GPIOs, and keep off its strapping pins, GPIO34 to 38. - The UART is 3.3 V on both sides. The ESP32's TX only drives the camera's RX while the camera has power: a driven RX back-powers an unpowered SoC, and some then fail to cold boot.
- The boot pin only ever pulls low or lets go, so it never feeds an unpowered camera. Pulled low through a power-on, it keeps the bootrom from reading the SPL, and the bootrom falls back to USB boot. Its level is set before it becomes an output, so it cannot glitch the flash of a running camera when the ESP32 boots.
- BOOTSEL is for boards that bring out the SoC's boot select, rather than relying on the
flash's DI: it moves with the boot pin, so whichever of the two is wired does the job. It
is pulled low by default, open-drain as the boot pin; it can be set to driven high on the
status page, or with
curl -X POST 'http://<host>.local/api/camera?bootsel=high'. Driven high, it is only driven while the unit has the camera's power switched on, since a pin driven into an unpowered SoC feeds it; a camera powered from elsewhere counts as on. - The power switch should switch the supply's + side. The camera's ground also reaches the ESP32 through the USB cable and the UART ground, so a switch on the ground side can be bypassed.
- The ESP32's own log is on UART0 at 115200 8N1: GPIO43 TX and GPIO44 RX on the S2 and S3 (D6 and D7 on a XIAO), GPIO37 TX and GPIO38 RX on the P4. On the S3, GPIO44 is the flash's HOLD instead, and the log is output only. Boards with a USB-UART bridge bring it out there; the S2 Mini has neither the bridge nor the pins. The camera's USB port is never a console.
- The pins are set in
src/main.rs, per chip; the status page lists the ones in use. The flash programmer's clip has pins of its own, in Flash chip.
Each release has two images per
chip (esp32s3, esp32s2, esp32p4) and a SHA256SUMS:
thingino-backpack-<chip>.binis a first install: the bootloader, the partition table and the app in one image, written at 0x0. It erases the saved Wi-Fi, so the unit starts in its setup portal.thingino-backpack-<chip>-app.binis an update, which keeps the Wi-Fi settings: upload it in the status page's Firmware section (see Firmware updates), or write it at 0x20000 over USB after erasing the OTA state at 0xf000.
esptool.py --chip esp32s3 write_flash 0x0 thingino-backpack-esp32s3.bin
esptool.py --chip esp32s3 erase_region 0xf000 0x2000
esptool.py --chip esp32s3 write_flash 0x20000 thingino-backpack-esp32s3-app.binUnits on 0.1.x have a single firmware slot and no OTA state: they take the first-install
image once, and then update over the network. Its Wi-Fi settings are kept by writing a
local build's bootloader.bin at 0x0, partition-table.bin at 0x8000 and app.bin at
0x20000 instead, after the same erase_region.
The images are built for 4 MB of flash and boot on 4, 8 and 16 MB modules. CI builds all
three on every push and publishes them when a v* tag is pushed.
Requirements:
- The Rust toolchain from espup (
channel = "esp"), which has the Xtensa targets of the S2 and S3 and the P4'sriscv32imafc-esp-espidf, plusldproxyandespflash(cargo install ldproxy espflash). - ESP-IDF v5.5.5, at
~/esp/esp-idf-v5.5.5by default (env.shsetsIDF_PATH).
Cargo fetches the daemon, the DFU core and the ESP-IDF USB host backend from thingino-dfu-rs at its v2.1.1 release.
./image.sh # ESP32-S3, images/: bootloader.bin, partition-table.bin, app.bin, full.bin
./image.sh psram # ESP32-S3 with octal PSRAM, images/psram/
./image.sh s2 # ESP32-S2, images/s2/
./image.sh p4 # ESP32-P4, images/p4/The first build of each compiles ESP-IDF and takes a while; each builds in a target directory of its own.
full.bin is the other three in one image, the one a release calls
thingino-backpack-<chip>.bin. Flash it once, with the chip and the directory that match:
esptool.py --chip esp32s3 write_flash 0x0 images/full.binAfter that, updates go over the network (Firmware updates), or over
USB with erase_region 0xf000 0x2000 and write_flash 0x20000 images/app.bin; both keep
the saved Wi-Fi settings. The build fails when the app outgrows its 1.9 MB OTA slot.
On the P4 there is nothing to set up: it takes its addresses on Ethernet. The S2 and S3,
with no saved network, open an access point named THINGINO-BACKPACK-xxxx (the
last four hex digits of its MAC) at 172.16.0.1, and answer the thingino cameras' setup
API. Either:
- use the thingino app, which finds it by the
THINGINO-prefix and derives the Wi-Fi key on the phone, or - join the access point and open http://172.16.0.1/ (most phones open it by themselves).
Enter the network, its passphrase, and a hostname (default thingino-backpack-xxxx). The
unit restarts and joins. It keeps rejoining after any outage, takes IPv6 addresses by
SLAAC as well as DHCPv4, and announces itself over mDNS.
To set it up again, press Reset Wi-Fi on the status page (or curl -X POST http://<host>.local/api/wifi-reset): it forgets the network, the hostname and the TX power
and restarts into the setup portal. Erasing the NVS partition (esptool.py erase_region 0x9000 0x6000) does the same without a network.
| Port | Service |
|---|---|
| 80 | Status page, /api/camera, /api/flash, /api/wifi, /api/ota |
| 2217 | Camera console, RFC 2217 |
| 3000 | Camera console, raw |
| 5050 | thingino-dfu daemon (dfu-remote) |
| 8888 | Flash programmer, flashrom's serprog (IPv4 only, for now) |
| 5353/udp | mDNS: the hostname, and _thingino._tcp for the thingino app |
<host> below is the hostname, as <host>.local, or an address.
thingino-dfu --host <host>.local:5050 -l # list what is on the USB port
thingino-dfu --host <host>.local:5050 -b # bootstrap a camera in the bootrom
thingino-dfu --host <host>.local:5050 -r dump.bin
thingino-dfu --host <host>.local:5050 -w image.bin --verifyThe unit holds no loaders, so the client sends the pair with each bootstrap: that takes
thingino-dfu 2.1.0 or later, and the web flasher at webflash.thingino.com does it too.
IPv6 addresses go in brackets and quoted: --host '[2001:db8::1]:5050'. In the web
flasher, choose remote mode and enter <host>.local:5050.
One client at a time across both console ports; a new connection takes the console over, and the old client is told who took it. The camera's output while nobody is connected is dropped.
socat -,rawer,escape=0x1d tcp:<host>.local:3000 # Ctrl-] leaves
python3 -m serial.tools.miniterm rfc2217://<host>.local:2217 115200RFC 2217 clients can set the baud rate, data bits, parity and stop bits, send a break, and drive the camera through the modem lines the way esptool's auto-reset circuit drives an ESP32's EN and IO0:
| DTR | RTS | Camera |
|---|---|---|
| on | off | boot pin held |
| off | on | power cut |
| on | on | unchanged |
| off | off | unchanged |
Terminals assert both lines when they open, which leaves the camera alone. The lines act once they have been stable for 100 ms, so a client that sets them one at a time never pulses the boot pin, and whatever they asserted is undone when the client disconnects. The UART goes back to 115200 8N1 then too.
The status page has buttons for all of these, and the same actions are an HTTP API:
curl http://<host>.local/api/camera
curl -X POST 'http://<host>.local/api/camera?action=bootrom'| Action | What it does |
|---|---|
power-on |
Switch the camera on |
power-off |
Switch the camera off |
power-cycle |
Off for a second, then on |
bootrom |
Hold the boot pin, power-cycle, release the pin as soon as the bootrom enumerates |
boot-hold |
Hold the boot pin |
boot-release |
Release the boot pin |
bootrom releases the pin as soon as the bootrom shows up, because U-Boot needs the flash
afterwards. It reports failure, and releases the pin, when nothing enumerates within 10
s, or when the camera was still on the USB bus after its power was cut: then the power
switch is not doing its job. A bootrom followed by thingino-dfu -b puts a camera into
the DFU gadget without anyone touching it.
Answers are JSON: {"ok":true,"message":...} or {"ok":false,"error":...}. GET /api/camera reports the power, the boot pin, the USB devices enumerated and their VID:PID,
how long a USB transfer has gone unanswered, the power cycles done for recovery, BOOTSEL's
sense and whether the USB port is connected. POST /api/camera?bootsel=low or high sets
BOOTSEL's sense, saved across restarts.
A camera whose SoC hosts a USB Wi-Fi module on the same lines as the backpack's USB cannot
have a second host on them. POST /api/camera?usb_port=off, or USB disconnected on the
status page, saved across restarts, takes the backpack off the lines: its root port powers
down, so it stops resetting and enumerating, and on the S2 and S3 its PHY lets go too, its
pull resistors off and its pads disconnected. usb_port=on takes them back, and a device on
the port enumerates. bootrom is refused while the port is off, as the bootrom only shows
up on USB.
- Off is not unwired. At its own restart the backpack's port comes up for a moment before the setting applies, and at USB high speed, which many Wi-Fi modules use, the stub of wire alone can upset the camera's link: keep D+ and D- short, or switch them with a USB switch IC.
- On the P4, only the port powers down: its high-speed PHY stays on the lines.
The unit speaks flashrom's serprog protocol on port 8888 and drives a SOIC-8 clip on the camera's flash chip, so flashrom 1.4.0 or later on any computer that reaches the unit reads and writes the chip over the network. The camera is either off, with the unit powering the chip, or parked in its bootrom on its own supply: see VCC and HOLD.
| ESP32-S3, -S2 | ESP32-P4 | Flash chip |
|---|---|---|
| GPIO5 | GPIO45 | CS, pin 1 |
| GPIO8 | GPIO47 | DO, pin 2 |
| GPIO7 | GPIO46 | CLK, pin 6 |
| GPIO9, the boot pin | GPIO21, the boot pin | DI, pin 5, wired already as the boot pin |
| GPIO3 | GPIO32 | VCC, pin 8 (or the unit's 3V3, on a bare chip) |
| GPIO44 (S2: GPIO40) | GPIO53 | HOLD, pin 7 |
| none | none | WP, pin 3: unconnected |
| GND | GND | GND, pin 4 |
- Pin 1 is the chip's dot, and the clip's red wire goes on it. A clip on backwards puts the unit's 3.3 V on the chip's ground pin, a short: the unit drops off Wi-Fi and browns out.
- 3.3 V chips only. A 1.8 V chip (W25Q...W, GD25LQ, MX25U, XM25QU) needs a level shifter and a 1.8 V supply.
- VCC and HOLD, when set to be driven, are only driven while flashrom has the pins enabled: VCC powers the chip first, then HOLD goes high so that nothing can pause the chip; afterwards both are let go. That suits a backpack soldered to the camera's flash for good. On the camera's board, VCC is its 3.3 V rail and HOLD one of the SoC's quad data lines, so outside a session they are the camera's, and it boots as if the backpack were not there.
- WP stays unconnected: a chip heeds it only to keep its status register locked, and only with quad mode off, so reading, writing and erasing work without it. A chip locked that way (SRWD set, quad mode off) needs WP tied to VCC before flashrom can clear its block protection.
- A GPIO gives about 40 mA. If powering the chip through pin 8 also feeds more of the camera's 3.3 V rail than that, the voltage sags; drive a high-side switch from the VCC GPIO instead.
- A clip on a bare chip can take VCC from the unit's 3V3 instead, with WP and HOLD tied to it.
- GPIO44 is an edge pin on every S3 board: D7 on a XIAO, RX on the Super Mini and the S3-Zero. It is UART0's RX too: on DevKitC-style boards the USB-UART bridge drives it high. That is HOLD's level in a session anyway, but outside one the bridge still drives it, into an unpowered chip through its HOLD pin or into a running camera's quad data line, so a backpack soldered to a camera's flash wants a board without a bridge there. The S2 Mini has no GPIO44; on the S2, HOLD is GPIO40, an edge pin there.
Each is a setting, driven (the default) or left alone, on the status page or with curl -X POST 'http://<host>.local/api/flash?vcc=alone&hold=alone'; GET /api/flash reports them.
They apply from the next flashrom run on, and are saved across restarts.
- VCC driven: the unit powers the chip through pin 8, and the camera has to be off. This suits a bare chip, and boards whose 3.3 V rail feeds little besides the flash.
- VCC left alone: the chip runs on the camera's own supply. This is for boards where the flash shares the SoC's 3.3 V rail, as on Ingenic cameras: powering that rail through the clip boots the SoC, its bootrom takes over the flash's pins, and reads come back as 0xFF or 0x00 after the first few milliseconds. Each flashrom run parks the camera first instead: its power cut for a second, then back on with the boot pin (and BOOTSEL) held for two, so the bootrom finds no SPL and leaves the flash alone. Where the SoC drives DI harder than the boot pin pulls it, as on a T23 board, only BOOTSEL parks it: wire the board's boot select there. The camera stays on, its power actions refused, until flashrom is done, and then goes off. Parking needs the unit's power switch to cut the camera's supply: a camera still on the USB bus, or still driving its UART TX, after the cut is refused, the boot pin untouched. A camera powered from elsewhere is parked by hand: hold the boot pin, power the camera on, then run flashrom, which takes the held pin for the camera parked and lets it go.
- HOLD driven: high through the session, so nothing pauses the chip. A chip with quad mode off needs it, on a board that leaves HOLD floating.
- HOLD left alone: for chips in quad mode, which take HOLD for a data line and ignore it, and boards that pull it up. On DevKitC-style boards, the USB-UART bridge drives GPIO44 whatever the setting, so unplug HOLD there for a board the bridge should not feed.
Then run flashrom from any computer that reaches the unit. Until flashrom's serprog client
gains IPv6 (1.8.0 has none), this is IPv4 only, though the unit listens on IPv6 too: where
<host>.local does not resolve to an IPv4 address, give it the one the status page lists.
curl -X POST 'http://<host>.local/api/camera?action=power-off' # when VCC is driven
flashrom -p serprog:ip=<host>.local:8888 # probe: names the chip
flashrom -p serprog:ip=<host>.local:8888 -r dump.bin
flashrom -p serprog:ip=<host>.local:8888 -r check.bin && cmp dump.bin check.bin
flashrom -p serprog:ip=<host>.local:8888 -w image.bin # erases, writes, verifies- With VCC driven, the camera has to be off: its power off, nothing on its USB port, and
its UART TX low, as an unpowered camera leaves it. The unit starts with the camera on, so
after it restarts, switch the camera off again.
Error: could not enable output buffersis the unit refusing to drive the clip for one of those reasons. - The unit drives the clip only while flashrom has the pins enabled. Until flashrom is
done, every camera action but
power-offis refused, and that one too while the camera is parked; a client that leaves, or one quiet for 30 s, gets the pins back to high-Z. - When several chip definitions match, flashrom asks for one: add
-cwith the name that matches the chip's marking, as-c "MX25L12835F/MX25L12873F". - Two reads that match are the check that the clip grips every leg; a write verifies itself.
- The SPI clock is 8 MHz unless flashrom asks for another (
spispeed=2M), up to 20 MHz. - A whole-chip read takes about 25 s for 16 MB. Every SPI command is a network round trip,
so writing a page takes about 13 ms: about 55 s for each megabyte that changes, and
flashrom skips the blocks that already match. Before writing, flashrom reads the whole
chip, and it verifies the whole chip afterwards, about 25 s each. With a layout and
-i,-N(--noverify-all) keeps both to the included regions, which leaves damage to the rest of the chip unchecked:
flashrom -p serprog:ip=<host>.local:8888 -l layout.txt -i uboot -N -w image.binThe hardware-development-lab panel
looks for thingino-backpack-* hosts among _thingino._tcp once a minute and adds each one
it finds, so a unit on the panel's network shows up there by itself; one elsewhere is added
by address. Each gets a card with the camera's power and boot pin, Enter bootrom, power
cycle, the USB devices on the port and the console, and the panel's MCP servers and skills
drive the unit the same way, flashing straight through its port 5050. The panel holds the
console for all of its viewers at once and gives it up when another client takes it over,
rather than taking it back.
The status page's Firmware section takes a release's thingino-backpack-<chip>-app.bin,
and the unit restarts into it; an HTTP POST does the same:
curl -X POST --data-binary @thingino-backpack-esp32s3-app.bin http://<host>.local/api/ota
curl http://<host>.local/api/ota # {"version":...,"slot":"ota_1","state":"valid"}- The image goes into the OTA slot that is not running, and nothing switches until it is checked: an image for another chip, a first-install image, or one that does not verify is refused, and the running firmware stays.
- A new firmware is on probation until the unit has an address on its network. If it resets before that, or has none within five minutes, the bootloader goes back to the firmware it replaced. Until then, further updates are refused.
- An update takes about 15 s, the restart included. Better not while a camera is being flashed: writing the unit's own flash pauses it for moments at a time.
A camera that stops serving USB without leaving the bus leaves a control transfer unanswered for good, and the ESP-IDF USB host has no transfer timeout. When that lasts 10 s, or when three port power cycles in a row fail to get the camera enumerated, the unit power-cycles the camera. It backs off from 30 s to 10 min while that keeps happening, and leaves a camera alone while its power is meant to be off or a bootrom entry is running.
On the S2 and S3, the radio transmits at up to 20 dBm. The status page's Wi-Fi section turns that down, to anywhere from 2 dBm, for a supply that browns out when the radio transmits or a flash clip whose reads come back wrong. The setting is kept across restarts and forgotten by Reset Wi-Fi, and the same is an HTTP API:
curl http://<host>.local/api/wifi # {"tx_dbm":20,"brownout":false}
curl -X POST 'http://<host>.local/api/wifi?tx_dbm=13'After a brownout reset the radio stays at 13 dBm or less until a reset for any other
reason, whatever the setting, and brownout is true.
The default build runs without PSRAM, which is what the stack sizes and the streaming are shaped for. The log prints the internal heap every 10 s (free, lowest ever, largest block) and every task's unused stack every minute. On a T31X with a console client attached, the lowest free heap is about 100 KB, reached during a bootstrap, and about 120 KB during reads and writes.
Nothing on the unit asks for credentials: anyone who can reach it can flash the camera, type into its console, cut its power, and replace the unit's own firmware. Keep it on a network you trust.
- Brownouts at Wi-Fi start-up (
BODin the log, reset loops): the radio's calibration is the current peak. After a brownout reset the radio comes up at 13 dBm instead of 20, until a reset for any other reason; a camera and the ESP32 on one weak USB port need a powered hub. Brownouts while the unit runs: lower the TX power on the status page. - flashrom reads that differ between runs: the clip's leads pick up the radio, or the
chip's supply sags when it transmits. Shorten the leads, put 100 nF across the chip's VCC
and GND, lower
spispeed=, or lower the TX power on the status page. A test chip on long leads read wrong at 20 dBm and right at 13 dBm until it was rewired. - flashrom aborts with
buffer overflow detected: the hostname did not resolve, and flashrom (1.4.0 to 1.8.0, at least) crashes instead of saying so. Give it the unit's IPv4 address. - RFC 2217 or the raw console stalls over IPv4 while IPv6 works: some access points'
hardware receive offload turns the Ethernet padding of tiny frames (1 to 5 bytes of TCP
payload, as keystrokes are) into payload, and the connection desyncs. OpenWrt's airoha
hardware GRO does this; turning it off (
ethtool -K <if> rx-gro-hw off) fixes it.
GPL-2.0-or-later, the same as thingino-dfu-rs, which the firmware is built on. See
LICENSE.