#!/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