ESP32-S3 摄像头图传：固件 + Slint 客户端 + 共享协议

两块 ESP32-S3-WROOM-1-N16R8 图传板（DVP 接口接 OV2640/OV3660/OV5640），向队伍客户端与裁判终端推 UDP 图传。固件是跑在 ESP-IDF 上的 Rust，用官方 esp32-camera 组件采集；客户端是 Rust + Slint 桌面程序。三个 crate 各自独立构建： . firmware，交叉编译到 Xtensa protocol/ 线路格式与帧重组，两端共用，无 ESP-IDF 依赖，有单元测试 client/ Slint 桌面客户端视频走 UDP 而非 TCP：实测传感器产出 22 fps，TCP MJPEG 只送出 1.9 fps，且只占用链路能力的 1%——链路是空的，帧堵在队头阻塞后面等一个实时画面等不起的重传计时器。改为独立数据报、不重传、缺片丢整帧后达到 20.8 fps。发现是双向的：板子每 2 秒广播 Hello，客户端广播 Subscribe，板子据此定向推流。板子身份由 MAC 派生，重启不变，所以客户端可以把绑定存进配置。裁判端同时收两块板子（每个发送方一个重组器），队伍端绑定其中一块并只显示自己那一边的血量。装甲板接口已预留（ArmorSource trait + ARMOR_PORT），当前无数据源，界面显示占位符。 vendor 了 esp32-camera 2.1.7：组件注册表的版本求解器找不到它，且需要打一处补丁（见 components/esp32-camera/target/esp32s3/ll_cam.c）。 .gitignore 三条 target/ 都锚定在根目录，因为 protocol/ 与 client/ 各自也是独立 crate；而 components/esp32-camera/target/ 是上游的按芯片分目录，里面是源码，必须保留。
2026-10-05 18:22:19 +08:00
commit 4f893ce140
134 changed files with 41128 additions and 0 deletions
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Builds the firmware with the credentials from .env (see .env.example).
+#
+# ESP-IDF location comes from .cargo/config.toml (IDF_PATH /
+# ESP_IDF_TOOLS_INSTALL_DIR), so no ESP-IDF activation is needed here as long as
+# those point at an installation you already have. Drop them to let esp-idf-sys
+# fetch its own pinned ESP-IDF.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if [ -f .env ]; then
+    set -a
+    # shellcheck disable=SC1091
+    . ./.env
+    set +a
+fi
+
+: "${WIFI_SSID:?set WIFI_SSID in .env (or export it) before building}"
+export WIFI_PASS="${WIFI_PASS:-}"
+
+cargo build --release "$@"
@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Builds, picks a flash offset that avoids the module's defective byte, flashes,
+# and prints the serial log.
+#
+# The module this was developed against has one byte in its SPI flash at
+# 0xFADE7 whose bits 5..7 cannot be programmed (see README). Whatever value the
+# app image places there gets corrupted, the image checksum fails, and the
+# bootloader refuses to boot it. The image itself is unaffected by where it is
+# placed in flash, so moving the app partition is enough: this picks the lowest
+# 64 KB-aligned offset whose byte at that address the flash can actually store.
+#
+# Usage: scripts/flash.sh [--monitor SECONDS]
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+readonly BAD_FLASH_ADDR="${BAD_FLASH_ADDR:-0xFADE7}"
+readonly ALIGN="${ALIGN:-0x10000}"
+readonly MAX_APP_SIZE="${MAX_APP_SIZE:-0x120000}"
+
+MONITOR_SECS=25
+if [ "${1:-}" = "--monitor" ]; then
+    MONITOR_SECS="${2:-25}"
+fi
+
+port="${ESP_PORT:-}"
+if [ -z "$port" ]; then
+    port=$(ls /dev/cu.usbmodem* /dev/cu.wchusbserial* /dev/cu.SLAB* /dev/cu.usbserial* 2>/dev/null | head -1 || true)
+fi
+if [ -z "$port" ]; then
+    echo "no serial port found; set ESP_PORT=/dev/cu.xxx" >&2
+    exit 1
+fi
+
+out=$(ls -d target/xtensa-esp32s3-espidf/release/build/esp-idf-sys-*/out/build 2>/dev/null | head -1 || true)
+
+echo "==> build"
+./scripts/build.sh
+
+echo "==> pick app offset"
+espflash save-image --chip esp32s3 --format esp-idf \
+    target/xtensa-esp32s3-espidf/release/esp32 /tmp/esp32-cam-app.bin >/dev/null
+
+read -r offset < <(python3 - <<PY
+import sys
+data = open("/tmp/esp32-cam-app.bin", "rb").read()
+bad = $BAD_FLASH_ADDR
+align = $ALIGN
+flash_size = 16 * 1024 * 1024
+for off in range(align, flash_size - len(data), align):
+    at = bad - off
+    if at < 0 or at >= len(data):
+        continue
+    if data[at] & 0xE0 == 0:          # top three bits must be storable
+        print(off)
+        break
+else:
+    sys.exit("no usable app offset found; this module's flash is too broken")
+PY
+)
+
+printf '0x%x\n' "$offset"
+
+# Write the chosen offset into partitions.csv.
+python3 - "$offset" <<'PY'
+import re, sys
+offset = int(sys.argv[1], 0)
+p = "partitions.csv"
+s = open(p).read()
+s2 = re.sub(r"^(factory,\s+app,\s+factory,\s+)0x[0-9a-fA-F]+",
+            lambda m: m.group(1) + "0x%06x" % offset, s, flags=re.M)
+if s2 != s:
+    open(p, "w").write(s2)
+    print("partitions.csv updated")
+else:
+    print("partitions.csv already at 0x%06x" % offset)
+PY
+
+echo "==> reconfigure + rebuild with the new table"
+rm -rf target/xtensa-esp32s3-espidf/release/build/esp-idf-sys-*
+./scripts/build.sh
+
+espflash save-image --chip esp32s3 --format esp-idf \
+    target/xtensa-esp32s3-espidf/release/esp32 /tmp/esp32-cam-app.bin >/dev/null
+
+out=$(ls -d target/xtensa-esp32s3-espidf/release/build/esp-idf-sys-*/out/build | head -1)
+
+# The rebuild can shift the image, so confirm before committing to the flash.
+python3 - <<PY || { echo "image moved onto the bad byte again; rerun" >&2; exit 1; }
+import sys
+data = open("/tmp/esp32-cam-app.bin", "rb").read()
+at = $BAD_FLASH_ADDR - $offset
+if not (0 <= at < len(data)) or data[at] & 0xE0:
+    print("byte at 0x%X is 0x%02X, not storable" % ($BAD_FLASH_ADDR, data[at] if 0 <= at < len(data) else -1))
+    sys.exit(1)
+print("byte at 0x%X is 0x%02X, storable" % ($BAD_FLASH_ADDR, data[at]))
+PY
+
+echo "==> flash $port"
+esptool_py=$(ls "$HOME"/.espressif/tools/python/*/venv/bin/python 2>/dev/null | head -1)
+"$esptool_py" -m esptool --chip esp32s3 --port "$port" --baud 460800 write-flash \
+    0x0 "$out/bootloader/bootloader.bin" \
+    0x8000 "$out/partition_table/partition-table.bin" \
+    "$offset" /tmp/esp32-cam-app.bin 2>&1 | grep -viE 'writing at|^\[1A' | tail -4
+
+if [ "$MONITOR_SECS" -gt 0 ]; then
+    echo "==> serial log (${MONITOR_SECS}s)"
+    python3 - "$port" "$MONITOR_SECS" <<'PY'
+import os, sys, termios, time
+fd = os.open(sys.argv[1], os.O_RDONLY | os.O_NOCTTY)
+a = termios.tcgetattr(fd)
+a[0] = a[1] = a[3] = 0
+a[2] = termios.CS8 | termios.CREAD | termios.CLOCAL
+a[4] = a[5] = termios.B115200
+a[6][termios.VMIN] = 0
+a[6][termios.VTIME] = 1
+termios.tcsetattr(fd, termios.TCSANOW, a)
+end = time.time() + float(sys.argv[2])
+while time.time() < end:
+    try:
+        d = os.read(fd, 4096)
+    except OSError:
+        break
+    if d:
+        sys.stdout.write(d.decode("utf-8", "replace"))
+        sys.stdout.flush()
+PY
+fi
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Finds a FLASH_PAD value that moves the firmware off a defective SPI flash byte.
+#
+# The module this was developed against has one byte at flash address 0xFADE7
+# whose bits 5..7 cannot be programmed, so whatever lands there gets corrupted
+# and the image checksum (and therefore the app) fails to boot. Growing
+# FLASH_PAD shifts .flash.text, which moves a different byte onto that address.
+# A byte is safe when its top three bits are zero, i.e. value <= 0x1F.
+#
+# Usage: scripts/pick-flash-pad.sh [max_attempts]
+# Prints the FLASH_PAD value to use, or exits non-zero if none was found.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Flash address of the defective cell, and the offset of the app partition.
+readonly BAD_FLASH_ADDR="${BAD_FLASH_ADDR:-0xFADE7}"
+readonly APP_OFFSET="${APP_OFFSET:-0x10000}"
+readonly MAX_ATTEMPTS="${1:-40}"
+
+image=$(mktemp -t esp32-app.XXXXXX.bin)
+trap 'rm -f "$image"' EXIT
+
+bad_offset=$(python3 -c "print($BAD_FLASH_ADDR - $APP_OFFSET)")
+
+echo "bad cell: flash $BAD_FLASH_ADDR (image offset $bad_offset)"
+
+for ((pad = 0; pad < MAX_ATTEMPTS; pad++)); do
+    FLASH_PAD="$pad" ./scripts/build.sh >/dev/null 2>&1 || {
+        echo "build failed for FLASH_PAD=$pad" >&2
+        exit 1
+    }
+
+    espflash save-image --chip esp32s3 --format esp-idf \
+        target/xtensa-esp32s3-espidf/release/esp32 "$image" >/dev/null 2>&1
+
+    byte=$(python3 - "$image" "$bad_offset" <<'PY'
+import sys
+data = open(sys.argv[1], "rb").read()
+off = int(sys.argv[2])
+print(data[off] if off < len(data) else -1)
+PY
+)
+
+    if (( byte >= 0 && (byte & 0xE0) == 0 )); then
+        echo "FLASH_PAD=$pad works: byte at $BAD_FLASH_ADDR would be 0x$(printf '%02X' "$byte")"
+        echo "set FLASH_PAD to $pad (in src/main.rs, or export it at build time)"
+        exit 0
+    fi
+
+    echo "  FLASH_PAD=$pad -> 0x$(printf '%02X' "$byte" 2>/dev/null || echo '??') (unsafe)"
+done
+
+echo "no safe FLASH_PAD found in 0..$((MAX_ATTEMPTS - 1)); this module's flash is too broken" >&2
+exit 1
@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Minimal UDP listener for the camera stream, used to verify the firmware.
+
+Not the real client - just enough to confirm datagrams arrive, that they
+reassemble into a valid JPEG, and to measure the frame rate independently of
+the Slint app.
+"""
+import socket, sys, time, collections
+
+HOST = "192.168.1.139"
+PORT = 5600
+DURATION = float(sys.argv[1]) if len(sys.argv) > 1 else 10.0
+
+# Must match protocol/src/lib.rs: MAGIC, HEADER_LEN, MAX_FRAGMENT_PAYLOAD,
+# DEFAULT_PORT. Duplicated here on purpose - this is a throwaway diagnostic, and
+# making it depend on the Rust crate would defeat the point of it being an
+# independent check of the wire format.
+HEADER = 20
+MAGIC = 0x4D564331
+FRAG = 1400
+
+sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+sock.bind(("", PORT))
+
+# Announce ourselves, exactly as the Slint client will.
+sock.sendto(b"\x00", (HOST, PORT))
+sock.settimeout(0.5)
+
+frag_bytes = FRAG
+frames = {}
+stats = collections.Counter()
+sizes = []
+start = time.time()
+last_print = start
+
+while time.time() - start < DURATION:
+    try:
+        data, _ = sock.recvfrom(2048)
+    except socket.timeout:
+        continue
+
+    stats["datagrams"] += 1
+
+    if len(data) < HEADER:
+        stats["short"] += 1
+        continue
+
+    magic = int.from_bytes(data[0:4], "little")
+    if magic != MAGIC:
+        stats["bad_magic"] += 1
+        continue
+
+    frame_id = int.from_bytes(data[4:8], "little")
+    frag_index = int.from_bytes(data[8:10], "little")
+    frag_count = int.from_bytes(data[10:12], "little")
+    total_len = int.from_bytes(data[12:16], "little")
+    width = int.from_bytes(data[16:18], "little")
+    height = int.from_bytes(data[18:20], "little")
+
+    payload = data[HEADER:]
+
+    if frame_id not in frames:
+        if frames:
+            stats["superseded"] += 1
+        frames[frame_id] = {
+            "buf": bytearray(total_len),
+            "seen": 0,
+            "count": frag_count,
+            "total": total_len,
+            "w": width,
+            "h": height,
+            "t0": time.time(),
+        }
+
+    f = frames[frame_id]
+    off = frag_index * frag_bytes
+    if off + len(payload) <= total_len:
+        f["buf"][off:off + len(payload)] = payload
+        f["seen"] += 1
+    else:
+        stats["overflow"] += 1
+
+    if f["seen"] >= f["count"]:
+        jpeg = bytes(f["buf"])
+        if jpeg[:2] == b"\xff\xd8" and jpeg[-2:] == b"\xff\xd9":
+            stats["good"] += 1
+            sizes.append((f["total"], f["w"], f["h"]))
+        else:
+            stats["corrupt"] += 1
+        del frames[frame_id]
+
+    now = time.time()
+    if now - last_print >= 2.0:
+        elapsed = now - last_print
+        print(
+            f"  {stats['good']/elapsed:5.1f} fps  "
+            f"datagrams={stats['datagrams']:5d}  "
+            f"superseded={stats['superseded']:4d}  corrupt={stats['corrupt']:3d}  "
+            f"good={stats['good']:4d}"
+        )
+        last_print = now
+
+sock.close()
+print()
+print("totals:", dict(stats))
+if sizes:
+    avg = sum(s[0] for s in sizes) / len(sizes)
+    print(f"avg frame: {avg:.0f} bytes, {sizes[0][1]}x{sizes[0][2]}")
+    print(f"throughput: {sum(s[0] for s in sizes)/DURATION/1024:.1f} kB/s")