Command-line reference

Run these commands from the board’s Linux console unless a section specifies the host computer. For build and flash commands, see the Make reference.

esp32-config

esp32-config

Opens the board configuration menu for system settings, networking, Bluetooth, interfaces, GPIO, memory/storage, and configuration backups. See esp32-config for its commands and setup steps.

s31-overlay

s31-overlay list
s31-overlay status
s31-overlay routes NAME
s31-overlay parameters NAME
s31-overlay describe NAME
s31-overlay check CONFIG_FILE
s31-overlay apply NAME [KEY=VALUE ...] [--volatile]
s31-overlay remove NAME [--volatile]
s31-overlay remove --all [--volatile]
s31-overlay restore

list shows installed overlays; status shows the active and saved sets. routes and parameters show the defaults and choices exported by an overlay. describe separates default, current, and saved values in tab-separated records. check validates a saved configuration against the installed catalog without applying it.

apply and remove update the named saved selection by default; remove --all clears the saved set. Use --volatile to leave saved selections unchanged. restore replaces the active set with the saved entries when the saved file exists. See Using overlays for examples and failure behavior.

s31-lpctl

s31-lpctl status
s31-lpctl ping
s31-lpctl sleep-test MS
s31-lpctl gpio-test PIN low|high [none|up|down] [MS]
s31-lpctl send WORD
s31-lpctl recv

Command	Description
`status`	Show firmware readiness, mailbox counters, and ping status
`ping`	Request a PING/PONG exchange
`sleep-test`	Run the LP timer test for 10–5000 ms while Linux remains running
`gpio-test`	Test an LP GPIO0–7 level, with optional pull and 10–5000 ms timeout
`send`	Send one 32-bit mailbox word
`recv`	Wait for one mailbox word and print it in hexadecimal

The GPIO test defaults to no pull and a 1000 ms timeout. Supply the pull argument before specifying a timeout. For example:

s31-lpctl gpio-test 3 high up 500

See LP core for setup and protocol details.

s31-selftest

s31-selftest [--quick|--stress] [--json] [--duration SECONDS]
             [--require-radio-traffic]

The default quick test checks system health and performs a small persistent write test. Stress mode adds concurrent CPU, XIP-read, persistent-write, and radio-health checks. Its default duration is 60 seconds, with a range of 10–3600 seconds.

s31-selftest --quick
s31-selftest --stress --duration 60 --json

--json prints one JSON result per line. In stress mode, --require-radio-traffic makes unchanged Wi-Fi/Bluetooth packet counters a failure; generate suitable traffic while the test runs.

s31-modload

s31-modload MODULE.ko [PARAM=VALUE ...]
s31-modload --remove MODULE_NAME

Loads a kernel module, including XZ-compressed modules, or removes one by its kernel name. Normal radio startup is handled by the board’s service scripts. Use this helper for module development after stopping applications that use the device.

HIL (hardware-in-the-loop) tools

These tools are used to automate hardware-in-the-loop testing for the ESP32-S31 platform.

On the host, list the runner options with:

python3 tools/hil/s31_hil.py --help

The runner coordinates s31-hil-agent on the S31 and optional peer firmware. See Hardware-in-the-loop testing for complete commands and fixture setup.

Wi-Fi diagnostics

iw dev
iw phy
wpa_cli -p /run/wpa_supplicant -i wlan0 status
ip addr show wlan0

The mac80211 SoftMAC frontend supports one station and does not expose firmware EAP-credential vendor commands. See Advanced Wi-Fi for AP, monitor, authentication, and suspend limitations.

Development utilities

The project includes sources for CoreMark, memory and libc tests, extension tests, and other diagnostics. Several are removed from the compact rootfs by post-build.sh. To add a tool to your image, follow Adding a userspace tool.