# SPDX-License-Identifier: MIT OR Apache-2.0
#
# HIL rig configuration for `m5stack-hil`. Copy to `hil.toml` (gitignored) and
# edit for your bench:
#
# cp hil.toml.example hil.toml
#
# Boards are NAMED here so nothing else has to spell out a MAC. A board's
# `/dev/serial/by-id/...` path is derived from its MAC, and both are facts about
# a rig rather than about the code — swapping hardware, or moving to a second
# rig, is an edit to this file and to nothing else.
#
# Looked for in this order: $M5STACK_HIL_CONFIG, then `hil.toml` here or in any
# parent directory, then ~/.config/m5stack-hil/hil.toml.
#
# Unknown keys are an ERROR, not something skipped — a typo must fail the run
# rather than silently leave a setting at its default.
# The rig used when --rig is not given.
default_rig = "bench"
[rigs.bench.cores3]
# A CoreS3 speaks over its own USB-Serial-JTAG, so the by-id path is derived
# from the MAC and is not restated. Find it with:
# ls /dev/serial/by-id/
mac = "1C:DB:D4:BA:83:38"
# Optional. A substring the application prints BEFORE its identity line. Giving
# one buys a real distinction: without it, "the board did not boot" and "this
# image carries no identity" are indistinguishable, and the harness says so
# rather than guessing which it was.
# banner = "m5stack-core"
# How the board is restarted. A `mac` board defaults to "probe-rs" — the CoreS3's
# USB-Serial-JTAG carries a real debug probe, and resetting through it does not
# depend on the serial adapter honouring RTS/DTR.
#
# probe-rs over JTAG, through the debug probe. Needs `chip`, since
# probe-rs addresses a target by name.
# serial-lines pulse the tty's RTS line from the harness itself, WITHOUT
# letting go of the port. The default for a `port` board.
# espflash the same pulse, from a subprocess that needs the port to
# itself — so the harness must release it across the reset and
# re-open into a boot already under way, losing the identity
# line the reset exists to read. The fallback, not the default.
#
# reset = "probe-rs"
# Optional flash settings; these are the CoreS3 defaults.
# chip = "esp32s3"
# flash_freq = "80mhz" # espflash defaults to 40mhz — see tools/README.md
# flash_size = "16mb"
# partition_table = "partitions.csv"
# A Fire27 sits behind a USB-serial bridge, so its by-id name is not derived
# from a MAC: name the port, and give the board a stable id of its own for the
# lock. Never a `ttyACM` index — those renumber on replug, and a lock keyed to
# one would let two runs claim the same board under two names.
#
# The bridge is NOT derived from an adapter serial the way a CoreS3's path is
# derived from its MAC, because M5Stack has shipped ESP32 boards behind more
# than one USB-serial chip — identical hardware, different names. This bench's
# Fire27 is a 1a86 (CH-series); the same board elsewhere is a Silicon Labs
# CP2104, which produces a longer path ending `-if00-port0`. Find yours with:
# ls /dev/serial/by-id/
#
# [rigs.bench.fire27]
# port = "/dev/serial/by-id/usb-1a86_USB_Single_Serial_5864000922-if00"
# id = "fire27-5864000922"
#
# Note the serial in that path is the ONLY thing separating this board from
# another 1a86 device on the same bench. Copy it from `ls`, do not retype it.
#
# The Fire27 console is UART0 at 1 Mbaud — NOT 115200. The ESP32's ROM and
# second-stage bootloader still talk at 115200, so their chatter arrives as
# unreadable bytes; only the application's own output is legible. Measured on
# this bench: a boot capture is ~13 kB of binary containing THREE newlines, so
# a "captured N lines" count means nothing on this board — the transcript is
# still complete, it is simply not text until the application starts.
#
# Two consequences. A `banner` must be a line the APPLICATION prints, never a
# bootloader one, since the latter is unreadable at this rate. And `banner` is
# more useful here than on a CoreS3, not less: it separates "never reached the
# application" from "this image carries no identity", which garbled noise
# cannot.
#
# The identity lands at ~0.000-0.001 s of uptime, against ~0.3 s on a CoreS3 —
# UART0 is live immediately, where the CoreS3 pays USB enumeration first.
# baud = 1000000
# banner = "m5stack-core"
#
# chip = "esp32" picks the ESP32 flash defaults, including flash_freq = "80mhz".
# If a freshly written board does not come up, try "40mhz" — espflash's own
# default, and the safe value for a part that cannot run at 80.
# chip = "esp32"
#
# Reset defaults to "serial-lines" for a `port` board: the harness pulses RTS
# itself, on the port it is already holding, so the boot is captured from the
# first byte. Verified on this bench, including the negative control — with the
# pulse stubbed out the identity is never captured, so the reset is genuinely
# the pulse and not the DTR edge a port open produces.
#
# If a board's auto-reset circuit does not respond, the symptom is "never
# reached the application" (loud, not silent) and the fallback is one line:
# reset = "espflash"
# A second rig defines the same board names against different hardware, and
# `--rig lab2` selects it. Nothing in the code or the scripts changes.
#
# [rigs.lab2.cores3]
# mac = "AA:BB:CC:DD:EE:FF"