esp32-config

Run esp32-config as root on the board’s console to open the configuration menu. Select a setting, edit its current values, then save and apply it. Back leaves the current page; Finish closes the tool. Submitted settings remain saved when you exit.

Menu

Page	Settings
System	Hostname, login password, date/time, startup program
Network	Wi-Fi network, IPv4 address, DNS
Bluetooth	Enabled state, device name, saved pairings
Interfaces	Peripheral selection, pins, parameters, GPIO, USB function
Memory & storage	Swap and a removable storage volume
Maintenance	Export, import, reset, full status

Pages use the drivers and tools installed in the running image. For example, USB device functions require gadget support, and mounting a volume requires its filesystem driver. A driver omitted from the image cannot be enabled by a menu selection. See Build configuration.

Routine settings take effect when submitted. Startup-program selections take effect at the next start of that program. Imported or reset settings are applied together after restarting Linux. These actions state when a restart is needed.

System commands

esp32-config system hostname [NAME]
esp32-config system password
esp32-config system time status|apply|sync
esp32-config system time configure ZONE AUTOMATIC SERVER
esp32-config system time set 'YYYY-MM-DD HH:MM:SS'
esp32-config system autostart status|enable|disable|start|stop
esp32-config system autostart configure EXECUTABLE [ARG ...]

hostname without NAME prompts for a new name. password opens the system password tool for root. For time configuration, AUTOMATIC is 0 or 1. EXECUTABLE is an absolute path; each ARG is passed literally. See System settings for examples and startup behavior.

Network commands

esp32-config wifi status|scan|configure|enable|disable|forget
esp32-config wifi connect SSID [psk|open]
esp32-config wifi configure-hex SSID_HEX [psk|open]
esp32-config network status
esp32-config network dhcp [auto|manual [DNS ...]]
esp32-config network static ADDRESS PREFIX GATEWAY_OR_- [DNS ...]

Interactive wifi configure asks for one SSID and one password, saves the profile, and connects. connect takes the SSID as an argument and reads one password from the terminal or standard input. open skips the password. configure-hex takes the exact SSID bytes encoded as hexadecimal.

Protected profiles accept an 8–63-byte password or a 64-digit hexadecimal PSK. The derived key is saved; the plaintext passphrase is not retained. For a protected network whose SSID contains a zero byte, use configure-hex and a precomputed PSK. Open networks with such an SSID need only configure-hex.

Noninteractive wifi configure reads three input lines: SSID, password, matching password. It only saves the profile. Use wifi connect, with one password line on standard input, for save-and-connect behavior.

A connection action returns 0 when connected, 1 on an apply failure, or 2 when the bounded wait ends with connection work still pending. Check wifi status before retrying. The connection workers continue after a pending result. Usage errors also return a nonzero status.

Address commands accept IPv4 addresses and up to three DNS servers. Use - for no gateway. Address settings reconnect enabled Wi-Fi; if Wi-Fi is off, they are saved for the next connection. See Wi-Fi and Bluetooth setup.

Bluetooth commands

esp32-config bluetooth info|status|enable|disable|restart
esp32-config bluetooth name [NAME]
esp32-config bluetooth clear-pairings

name without a value prints the saved name. Names contain 1–29 bytes and no control characters. The default is S31 Radio. Changing an enabled device’s name restarts Bluetooth. clear-pairings clears the current controller’s Classic and BLE keys and restarts its running service.

Enabled Bluetooth provides Classic A2DP transport and a BLE peripheral. The bundled application does not decode audio for PCM playback. The bluetooth scan command reports that scanning is unsupported; there is no scanning item in the menu.

Changing the Wi-Fi/Bluetooth enabled combination reloads their shared radio. Setting an unchanged enabled state does nothing; use apply wifi or bluetooth restart for recovery. See the network guide for pairing and service details.

Interfaces and GPIO

esp32-config overlay COMMAND [ARG ...]
esp32-config gpio list|status|apply|reset
esp32-config gpio set LINE application|low|high
esp32-config gpio set LINE input [none|up|down]
esp32-config gpio read LINE

overlay forwards arguments to s31-overlay, including --volatile. The interface page reads default, current, and saved settings separately. Fixed pins are displayed without an editable GPIO field.

GPIO settings apply immediately, remain held after the menu exits, and are restored by the Linux startup service. application releases the line and removes its saved assignment. reset releases all GPIOs owned by the tool and clears their saved assignments. read reads a managed input; for a managed output it reports the configured level. For usage and ownership, see Use peripherals.

The following diagnostic commands are available from the CLI:

esp32-config gpio info [CHIP]
esp32-config gpio get CHIP LINE
esp32-config gpio pulse CHIP LINE VALUE [SECONDS]

pulse is a temporary output for 1–30 seconds, defaulting to 3 seconds. It does not create a saved assignment and is not part of the configuration menu.

Memory, storage, and USB

esp32-config storage status
esp32-config storage swap status|disable|apply|stop
esp32-config storage swap enable DEVICE
esp32-config storage configure DEVICE PATH AUTOSTART READONLY
esp32-config storage mount|unmount
esp32-config storage autostart 0|1
esp32-config usb status|apply|stop
esp32-config usb configure MODE [SERIAL_LOGIN [IP/PREFIX]]

Storage commands select an existing swap device or filesystem; they do not format it. Devices may be /dev/... paths or UUID=... identifiers. AUTOSTART and READONLY are 0 or 1. The mount path is an empty directory under /mnt or /media. See Memory and storage.

USB MODE is host, serial, or network. SERIAL_LOGIN is 0 for an application serial port or 1 for a Linux login console. The network mode uses ECM and defaults to board address 192.168.7.2/24. See USB functions for host setup and role changes.

Apply settings and manage backups

esp32-config status
esp32-config apply [all|system|wifi|bluetooth|gpio|storage|usb]
esp32-config stop
esp32-config maintenance backup PATH.tar
esp32-config maintenance restore PATH.tar
esp32-config maintenance reset network|bluetooth|interfaces|gpio|system|memory|all

apply defaults to all. It reapplies system, radio, GPIO, USB, and storage settings. It does not launch the startup program or replace the active overlay set. apply system applies the hostname and time settings. stop stops the managed Wi-Fi connection while retaining its saved policy.

Backups cover settings managed by esp32-config. Import and reset preserve user programs, login passwords, and Bluetooth pairing keys. Restart Linux to apply imported or reset settings. See Configuration for backup examples, persistence, and recovery.

Persistent files

File under /etc/esp32-conf	Contents
system.conf	Hostname
wifi.conf	Wi-Fi enabled state, interface, SSID identifier, IPv4/DNS policy
wpa_supplicant.conf	Saved station profile
bluetooth.conf	Enabled state, controller selection, BLE policy, device name
overlays.conf	Saved peripheral selections and parameters
gpio.conf	Managed GPIO assignments
time.conf	Time zone, automatic-time selection, time server
autostart.conf, autostart.args	Startup program and literal arguments
swap.conf	Swap selection and startup policy
storage.conf	Selected volume, mount path, access, startup policy
usb.conf	USB mode, serial login selection, network address, device identity

The configuration directory uses mode 0700; settings files use mode 0600. Login passwords are managed separately by the system password tool. Runtime state is stored under /run/esp32-config and is cleared at reboot.

The frontend is buildroot-external/board/esp32-s31/overlay/usr/sbin/esp32-config. Its settings modules are under the adjacent usr/lib/esp32-config directory.