Files
qlcplus/scripts/flash_luxdmx_xiao.sh

220 lines
6.6 KiB
Bash
Executable File

#!/usr/bin/env bash
# Flash LuxDMX onto a Seeed Studio XIAO ESP32S3.
#
# The XIAO is an ESP32-S3R8 (octal 8 MB PSRAM, native USB only). It shows up
# as an Espressif "USB JTAG/serial" port (/dev/ttyACM*), not a ttyUSB UART
# dongle. This downloads the current LuxDMX release and writes the
# octal-PSRAM image. esptool detects the flash size and rewrites the image
# header to match (this board reports 16 MB). The partition table ends at
# 4 MB, so either size fits. The write is a full erase, so the first boot
# opens the setup access point.
#
# scripts/flash_luxdmx_xiao.sh
# scripts/flash_luxdmx_xiao.sh --port /dev/ttyACM0
# scripts/flash_luxdmx_xiao.sh --plain # leave the PSRAM unused
# scripts/flash_luxdmx_xiao.sh --version v1.0.273
# scripts/flash_luxdmx_xiao.sh --dry-run
#
# A full USB flash erases saved Wi-Fi and config. To update a board that is
# already set up, use the device's own Firmware Update page instead.
#
# After it boots, join the open Wi-Fi "LuxDMX-setup" and open
# http://192.168.4.1. In /config apply the "Seeed XIAO ESP32-S3" template:
# DMX data is D0 (GPIO1) and the RDM return is D1 (GPIO2). The DevKit
# defaults (GPIO16/17) are not broken out on this board.
set -euo pipefail
REPO="tombueng/LuxDMX"
TAG="latest"
PORT=""
PLAIN=0
YES=0
DRY=0
BAUD=921600
usage() {
sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'
exit 2
}
while [[ $# -gt 0 ]]; do
case "$1" in
--port) PORT="${2:?}"; shift 2 ;;
--version) TAG="${2:?}"; shift 2 ;;
--baud) BAUD="${2:?}"; shift 2 ;;
--plain) PLAIN=1; shift ;;
--yes) YES=1; shift ;;
--dry-run) DRY=1; shift ;;
-h|--help) usage ;;
*) echo "Unknown option: $1" >&2; usage ;;
esac
done
# Ubuntu's esptool package is missing the ESP32-S3 flasher stub, so a
# version check is not enough. Use it only when that stub is actually there.
esptool_has_s3_stub() {
"$1" - << 'PY'
import pathlib, sys
try:
import esptool
except ImportError:
sys.exit(1)
root = pathlib.Path(esptool.__file__).resolve().parent / "targets" / "stub_flasher"
ok = (root / "stub_flasher_32s3.json").is_file() or any(root.glob("*/esp32s3.json"))
sys.exit(0 if ok else 1)
PY
}
if esptool_has_s3_stub python3; then
ESPTOOL=(python3 -m esptool)
else
VENV="${XDG_CACHE_HOME:-$HOME/.cache}/luxdmx/esptool-venv"
if [[ ! -x "$VENV/bin/python" ]] || ! esptool_has_s3_stub "$VENV/bin/python"; then
echo "System esptool has no ESP32-S3 stub. Installing one into ${VENV}…"
python3 -m venv "$VENV"
"$VENV/bin/pip" install -q 'esptool>=4.8,<5'
fi
ESPTOOL=("$VENV/bin/python" -m esptool)
fi
if [[ "$PLAIN" -eq 1 ]]; then
BOOT="bootloader-esp32s3.bin"
PARTS="partitions-esp32s3.bin"
APP="firmware-esp32s3.bin"
IMAGE="plain ESP32-S3 (PSRAM left unused)"
else
BOOT="bootloader-esp32s3-psram.bin"
PARTS="partitions-esp32s3-psram.bin"
APP="firmware-esp32s3-psram.bin"
IMAGE="ESP32-S3 octal PSRAM (XIAO ESP32S3 / S3R8)"
fi
find_port() {
if [[ -n "$PORT" ]]; then
[[ -e "$PORT" ]] || { echo "Port not found: $PORT" >&2; exit 1; }
echo "$PORT"
return
fi
local -a matches=()
local p
shopt -s nullglob
for p in /dev/serial/by-id/*; do
case "$p" in
*[Ee]spressif*|*[Ss]eeed*|*[Xx][Ii][Aa][Oo]*)
matches+=("$(readlink -f "$p")")
;;
esac
done
shopt -u nullglob
if [[ ${#matches[@]} -eq 1 ]]; then
echo "${matches[0]}"
return
fi
if [[ ${#matches[@]} -gt 1 ]]; then
echo "More than one Espressif/Seeed serial port. Pass --port." >&2
printf ' %s\n' "${matches[@]}" >&2
exit 1
fi
shopt -s nullglob
matches=(/dev/ttyACM*)
shopt -u nullglob
if [[ ${#matches[@]} -eq 1 && -e "${matches[0]}" ]]; then
echo "${matches[0]}"
return
fi
echo "No XIAO found. Plug in the USB-C port, then re-run." >&2
echo "If it still does not appear: hold B, tap R, release B, and pass --port." >&2
exit 1
}
CACHE_ROOT="${XDG_CACHE_HOME:-$HOME/.cache}/luxdmx"
mkdir -p "$CACHE_ROOT"
mapfile -t DL < <(python3 - "$CACHE_ROOT" "$TAG" "$BOOT" "$PARTS" "boot_app0.bin" "$APP" << 'PY'
import json, pathlib, sys, urllib.request
cache_root, tag, *names = sys.argv[1:]
api = f"https://api.github.com/repos/tombueng/LuxDMX/releases/tags/{tag}"
req = urllib.request.Request(api, headers={"Accept": "application/vnd.github+json", "User-Agent": "luxdmx-flash"})
with urllib.request.urlopen(req, timeout=60) as resp:
release = json.load(resp)
name = release.get("name") or release.get("tag_name") or tag
# "Latest → v1.0.273 (....)" — cache by the version, not the moving tag.
version = name
for token in name.replace("→", " ").replace("(", " ").split():
if token.startswith("v") and token[1:2].isdigit():
version = token
break
assets = {a["name"]: a for a in release.get("assets", [])}
missing = [n for n in names if n not in assets]
if missing:
sys.exit(f"Release {version} has no {', '.join(missing)}")
dest = pathlib.Path(cache_root) / version
dest.mkdir(parents=True, exist_ok=True)
for n in names:
path = dest / n
size = assets[n]["size"]
if path.is_file() and path.stat().st_size == size:
continue
url = assets[n]["browser_download_url"]
tmp = path.with_suffix(path.suffix + ".part")
urllib.request.urlretrieve(url, tmp)
if tmp.stat().st_size != size:
tmp.unlink(missing_ok=True)
sys.exit(f"Short download: {n}")
tmp.replace(path)
print(version)
print(dest)
PY
)
VERSION="${DL[0]}"
DIR="${DL[1]}"
PORT="$(find_port)"
echo "LuxDMX ${VERSION} (${IMAGE})"
echo "Port ${PORT} baud ${BAUD}"
echo "This erases the whole flash, including saved Wi-Fi and config."
if [[ "$DRY" -eq 1 ]]; then
echo "Dry run — not flashing."
exit 0
fi
if [[ "$YES" -ne 1 ]]; then
if [[ ! -t 0 ]]; then
echo "Pass --yes to flash without a prompt." >&2
exit 1
fi
read -r -p "Flash now? [y/N] " ans
[[ "$ans" == [yY] ]] || { echo "Cancelled."; exit 1; }
fi
set +e
"${ESPTOOL[@]}" --chip esp32s3 --port "$PORT" --baud "$BAUD" \
--before default_reset --after hard_reset \
write_flash --erase-all --flash_mode keep --flash_freq keep --flash_size detect --compress \
0x0000 "${DIR}/${BOOT}" \
0x8000 "${DIR}/${PARTS}" \
0xe000 "${DIR}/boot_app0.bin" \
0x10000 "${DIR}/${APP}"
rc=$?
set -e
if [[ $rc -ne 0 ]]; then
echo >&2
echo "Flash failed. Put the XIAO in download mode and run this again:" >&2
echo " hold B, tap R, release B, then: $0 --port $PORT --yes" >&2
exit $rc
fi
cat << 'EOF'
Flashed. On first boot the XIAO opens an open Wi-Fi network:
SSID LuxDMX-setup
URL http://192.168.4.1
In /config, apply the "Seeed XIAO ESP32-S3" template so the DMX pins
match the header (D0 = data out, D1 = RDM return). Then point QLC+
Art-Net at the address shown there, universe 0.
EOF