Files

315 lines
14 KiB
Bash
Executable File

#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# Flash a XIAO nRF52840 through its UF2 drive -- to a named board, and verified.
#
# tools/xiao_uf2_flash.sh <firmware.uf2> [target]
#
# target USB serial (full or unique suffix), or a board name/alias from the
# local config (tools/mctools_config.py).
# Omit only when exactly one board is plugged in.
#
# XIAO_UF2_WAIT=300 seconds to wait for UF2 mode (default 90). Worth raising
# when the board has to be double-tapped by hand.
#
# Get the board into UF2 mode with 'dfu' on its console (deterministic), or by
# double-tapping its small RESET button.
#
# What it refuses to do, because each of these has actually gone wrong here:
# - flash an image older than the build that produced it (pio run and
# pio run -t create_uf2 refresh different artifacts; x3 silently ended up
# two commits behind the rest of the fleet that way)
# - guess which board to write to when several are in UF2 mode (every drive
# is labelled XIAO-SENSE, in plug order, so the label proves nothing)
# - write to a board other than the one you named
# - report success without reading the version back off the board (the first
# version of this script printed x4's port after flashing x3)
#
# NEVER uses the 1200-baud touch: it only requests the bootloader's SERIAL_ONLY
# mode, so no drive ever appears, and a second touch in one power session wedges
# the board out of USB and BLE with no self-recovery.
set -uo pipefail
case "${1:-}" in -h | --help)
sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0"
exit 0
;;
esac
die() {
echo "CHYBA: $*" >&2
exit 1
}
UF2="${1:-}"
TARGET="${2:-}"
[ -n "$UF2" ] && [ -f "$UF2" ] || {
echo "usage: $(basename "$0") <firmware.uf2> [serial|board]" >&2
exit 1
}
# Board names/aliases come from the local config (tools/mctools_config.py);
# a serial or its unique suffix passes through.
if [ -n "$TARGET" ] && SN="$(python3 "$(dirname "$0")/mctools_config.py" serial "$TARGET" 2>/dev/null)"; then
TARGET="$SN"
fi
# A .hex or .zip dropped on a UF2 drive is silently ignored by the bootloader and
# looks like a successful flash, so check the container before trusting it.
# UF2 blocks start with the magic 0x0A324655 ("UF2\n").
head -c4 "$UF2" | grep -q 'UF2' || die "$UF2 neni UF2 obraz (chybi magic 'UF2\\n')"
echo "== image: $UF2 ($(stat -c%s "$UF2") B)"
ELF="$(dirname "$UF2")/firmware.elf"
if [ -f "$ELF" ] && [ "$ELF" -nt "$UF2" ]; then
die "$(basename "$UF2") je STARSI nez firmware.elf -- nalil bys stary obraz.
Sprav: pio run -e <env> && pio run -e <env> -t create_uf2"
fi
# Read the version out of the UF2 PAYLOAD, not the raw file. A UF2 is 512-byte
# blocks of 32 B header + 256 B data, so any string in the image can be cut in
# half by a block boundary -- and then a plain grep over the file finds nothing
# and this script refuses a perfectly good build. That is not hypothetical: it
# happened to SenseCap_mast_rpt on 15. 8. 2026 (the version was in the ELF the
# whole time), and it cost a hand-copied flash and a board that had to be
# replugged. Stitching the payload back together makes the check depend on the
# image rather than on where the linker happened to put the string.
WANT_VER="$(
python3 - "$UF2" <<'PY' 2>/dev/null || true
import re, sys
raw = open(sys.argv[1], "rb").read()
payload = b"".join(raw[i+32:i+288] for i in range(0, len(raw), 512))
m = re.search(rb"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", payload)
if m: print(m.group(0).decode())
PY
)"
if [ -z "$WANT_VER" ]; then
die "obraz nema verzi od tools/build_version.py -- po flashi by neslo overit,
co na desce doopravdy je. Zapoj do envu: extra_scripts = \${stamped.extra_scripts}"
fi
echo "== verze v obrazu: $WANT_VER"
[ -n "$TARGET" ] && echo "== cil: $TARGET"
# Resolve UF2 drives THROUGH SYSFS, never by label: every XIAO drive is called
# XIAO-SENSE (then XIAO-SENSE1, ...) assigned in plug order, so with several
# boards on the bus the label says nothing about which board you are writing to.
find_uf2_boards() {
local d s blk
for d in /sys/bus/usb/devices/*/; do
s="$(cat "$d/serial" 2>/dev/null)" || continue
[ "$(cat "$d/idVendor" 2>/dev/null)" = "2886" ] || continue
blk="$(ls -d "$d"*/host*/target*/*/block/* 2>/dev/null | head -1)" || true
[ -n "$blk" ] && echo "$s /dev/$(basename "$blk")"
done
}
# Companion builds have no text console, so no `dfu` command: those boards can
# only be double-tapped by hand, and 90 s turned out to be shorter than the round
# trip of asking someone to do it. Overridable rather than just longer, so an
# unattended flash still fails fast.
WAIT="${XIAO_UF2_WAIT:-90}"
echo -n "== cekam na UF2 rezim, ${WAIT}s (\"dfu\" na konzoli, nebo dvojklik RESET) "
SERIAL=""
DISK=""
for _ in $(seq 1 "$WAIT"); do
mapfile -t found < <(find_uf2_boards)
if [ -n "$TARGET" ]; then # keep only the board asked for
mapfile -t found < <(printf '%s\n' "${found[@]:-}" | grep -F "$TARGET" || true)
fi
if [ "${#found[@]}" -gt 1 ]; then
echo
{
echo "${#found[@]} desek v UF2 rezimu -- nevim, ktera je ta tva:"
printf ' %s\n' "${found[@]}"
echo "Zadej cil: $(basename "$0") $UF2 <serial|board>"
} >&2
exit 1
fi
if [ "${#found[@]}" -eq 1 ] && [ -n "${found[0]}" ]; then
SERIAL="${found[0]%% *}"
DISK="${found[0]##* }"
break
fi
echo -n "."
sleep 1
done
echo
[ -n "$DISK" ] || die "do ${WAIT} s se v UF2 rezimu neobjevila${TARGET:+ deska $TARGET}"
echo "== deska: $SERIAL disk: $DISK"
# Mount with retries: the drive appears a moment before the desktop automounter
# gets to it, and udisksctl can lose that race, so a single attempt fails on a
# board that is perfectly fine. Observed on the very first `dfu`-driven flash.
MNT=""
for _ in $(seq 1 12); do
MNT="$(lsblk -no MOUNTPOINT "$DISK" | head -1)"
[ -n "$MNT" ] && break
udisksctl mount -b "$DISK" >/dev/null 2>&1 || true
sleep 1
done
[ -n "$MNT" ] || die "disk $DISK se nepodarilo namountovat ani na 12 pokusu
Zkus rucne: udisksctl mount -b $DISK"
echo "== mount: $MNT -- kopiruju"
# The board resets itself the moment it has all the blocks, so cp/sync failing
# at the very end is normal, not an error.
cp "$UF2" "$MNT/" 2>/dev/null || true
sync 2>/dev/null || true
echo -n "== cekam, az disk zmizi (= bootloader obraz prevzal) "
GONE=0
for _ in $(seq 1 30); do
find_uf2_boards | grep -q "^$SERIAL " || {
GONE=1
break
}
echo -n "."
sleep 1
done
echo
[ "$GONE" -eq 1 ] || die "disk nezmizel -- flash nejspis neprobehl"
# Wait for THIS board, matched on its serial. "Some XIAO came back on USB" is
# worthless with four of them plugged in.
echo -n "== cekam na navrat desky $SERIAL "
PORT=""
for _ in $(seq 1 45); do
for d in /sys/bus/usb/devices/*/; do
[ "$(cat "$d/serial" 2>/dev/null)" = "$SERIAL" ] || continue
[ "$(cat "$d/idProduct" 2>/dev/null)" = "8044" ] || continue
PORT="$(ls /dev/serial/by-id/*"$SERIAL"*-if00 2>/dev/null | head -1)" || true
done
[ -n "$PORT" ] && break
echo -n "."
sleep 1
done
echo
[ -n "$PORT" ] || die "$SERIAL se do 45 s neohlasila jako aplikace"
# The actual proof: ask the board what it is running. Anything less and a flash
# that quietly did nothing still reports success.
#
# The same trip also SETS THE CLOCK, because this is the one moment when a host
# is provably talking to the board. Every clock in this firmware is volatile
# unless the board has GPS or an I2C RTC: `VolatileRTCClock` starts in May 2024
# and only ticks from millis(). A node with a wrong clock is not a cosmetic
# problem -- the RTC stamps every advert it transmits, and receivers drop a stale
# timestamp as a replay. Measured 7. 8. 2026: bench-board had been running 811 days
# behind since deployment, and bench board x1 was 812 days behind, both simply
# because nobody ever typed `time <epoch>`.
GOT="$(
python3 - "$PORT" <<'PY' 2>/dev/null || true
import re, struct, sys, time
try:
import serial
except ImportError:
sys.exit(0)
# Retry: the port enumerates a second or two before the firmware is answering on
# it, so a single attempt calls a perfectly good flash "unverified" -- which is
# worse than no check, because it teaches you to ignore the tool.
for attempt in range(5):
try:
s = serial.Serial(sys.argv[1], 115200, timeout=1); s.dtr = True; s.rts = True
time.sleep(2.5); s.reset_input_buffer()
# Throwaway newline first. The board's own line buffer can still hold a
# fragment from before the reset, and whatever is sent next gets appended
# to it -- so the first real command comes back "Unknown command" and the
# flash is declared unverified even though it landed. Cost this exactly
# one wrong conclusion about x4.
s.write(b"\r\n"); s.flush(); time.sleep(0.5); s.reset_input_buffer()
s.write(b"ver\r\n"); s.flush(); time.sleep(2.0)
out = s.read(s.in_waiting or 1).decode("utf-8", "replace")
m = re.search(r"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", out)
if m:
print("VER\t" + m.group(0))
# Set the clock, then read it back. The read-back is what decides:
# `time` answers "(ERR: clock cannot go backwards)" when the board is
# already right -- which happens once the build epoch seeds the RTC,
# and is SUCCESS, not failure. Never trust the setter's own reply.
s.reset_input_buffer()
s.write(("time %d\r\n" % int(time.time())).encode()); s.flush()
time.sleep(1.5); s.reset_input_buffer()
s.write(b"clock\r\n"); s.flush(); time.sleep(1.5)
got = s.read(s.in_waiting or 1).decode("utf-8", "replace")
c = re.search(r"\d{1,2}:\d{2} - \d{1,2}/\d{1,2}/\d{4} UTC(?: \(epoch \d+\))?", got)
print("CLOCK\t" + (c.group(0) if c else "?"))
s.close(); break
# No text console means this is a companion_radio build, which has no
# `ver` command at all -- ask in its own language rather than calling a
# perfectly good flash unverified (it did exactly that on x2).
# CMD_DEVICE_QUERY(22) -> RESP_CODE_DEVICE_INFO(13); firmware_version is
# the 20-byte field at offset 60. Framing: '<' + uint16 LE len + payload
# outbound, '>' + len + payload back.
s.reset_input_buffer()
s.write(b"<" + struct.pack("<H", 2) + bytes([22, 10])); s.flush()
time.sleep(1.0)
buf = s.read(s.in_waiting or 1)
# The port stays OPEN here on purpose. It used to be closed on this line,
# before the reply was even parsed -- which was harmless while the only
# thing left to do was print, and became a PortNotOpenError the moment
# the clock was set afterwards (caught by the outer handler, so it looked
# like four silent retries printing VER over and over). Closed on both
# exits below instead.
i = buf.find(b">")
if i >= 0 and len(buf) >= i + 3:
ln = struct.unpack("<H", buf[i+1:i+3])[0]
f = buf[i+3:i+3+ln]
if len(f) >= 80 and f[0] == 13:
v = f[60:80].split(b"\0")[0].decode("utf-8", "replace")
if v:
print("VER\t" + v)
# Companion builds have no `time` command at all -- the app
# sets the clock with CMD_SET_DEVICE_TIME(6). Same guard as
# the console (`secs >= curr`), so an ERR frame here is not a
# failure either; CMD_GET_DEVICE_TIME(5) -> RESP(9) decides.
now = int(time.time())
s.reset_input_buffer()
fr = bytes([6]) + struct.pack("<I", now)
s.write(b"<" + struct.pack("<H", len(fr)) + fr); s.flush()
time.sleep(1.0); s.reset_input_buffer()
s.write(b"<" + struct.pack("<H", 1) + bytes([5])); s.flush()
time.sleep(1.0)
rb = s.read(s.in_waiting or 1)
shown = "?"
j = rb.find(b">")
if j >= 0 and len(rb) >= j + 3:
rl = struct.unpack("<H", rb[j+1:j+3])[0]
rf = rb[j+3:j+3+rl]
if len(rf) >= 5 and rf[0] == 9:
t = struct.unpack("<I", rf[1:5])[0]
shown = time.strftime("%H:%M - %-d/%-m/%Y UTC",
time.gmtime(t)) + " (epoch %d)" % t
print("CLOCK\t" + shown)
s.close(); break
s.close() # neither dialect answered -- close before the retry reopens
except Exception:
pass
time.sleep(3)
PY
)"
GOT_VER="$(printf '%s\n' "$GOT" | sed -n 's/^VER\t//p' | head -1)"
GOT_CLOCK="$(printf '%s\n' "$GOT" | sed -n 's/^CLOCK\t//p' | head -1)"
if [ -z "$GOT_VER" ]; then
echo "!! deska neodpovedela ani konzoli, ani companion protokolu -- flash NEOVERENY (drzi konzoli BLE klient?)" >&2
exit 2
fi
if [ "$GOT_VER" != "$WANT_VER" ]; then
die "deska hlasi $GOT_VER, ale v obrazu bylo $WANT_VER -- flash NEPROSEL"
fi
echo "== OK: $SERIAL bezi $GOT_VER ($PORT)"
# Warn rather than fail: a wrong clock does not mean the flash was bad, and this
# script's contract is "the image landed". But it must not pass silently -- an
# unset clock is exactly what went unnoticed on x3 for 811 days.
# Only the year is checked, because that is what a volatile RTC gets wrong: it
# comes up in 2024 and stays there. (Around midnight on 31 December this warns
# for one minute on a board that is actually right. Non-fatal, once a year.)
case "$GOT_CLOCK" in
"") echo "!! hodiny se necetly zpatky -- nastav je rucne: time \$(date +%s)" >&2 ;;
"?") echo "!! hodiny neodpovedely ve znamem formatu -- zkontroluj 'clock' rucne" >&2 ;;
*"/$(date -u +%Y)"*)
echo "== hodiny: $GOT_CLOCK"
;;
*) echo "!! hodiny hlasi $GOT_CLOCK -- nesedi rok, nastav je rucne: time \$(date +%s)" >&2 ;;
esac