Terminal

The ESPurna firmware outputs debug information to the terminal interface. You only have to connect your USB2UART board to the TX, RX and GND pins in your board and open a terminal at 115200 baud (8,N,1). Not all devices have serial debug output enabled. It is controlled by build-time flag DEBUG_SERIAL_SUPPORT and, for example, Sonoff Dual and Sonoff RF Bridge have it disabled.

As an alternative you can remotely connect to the device using Telnet. If you activated Telnet on the administration page of the web interface, use telnet <ip> (no password needed) / nc <ip> 23 to connect to it. Similarly, Debug panel in the web interface allows you to view device log and enter commands.

We also have a limited support of terminal commands by using MQTT and HTTP API (see build options below).

Terminal does not only shows information about what the device is doing, but it also accepts several commands thanks to the built-in command line library (see code/espurna/terminal.cpp). You can get a list of these commands typing help / commands and enter. It's recommended to enable echo to see what you are typing.

Warning! There is a known issue that backspace or delete won't work while using Serial.

Configuration

Configuration key	Build flag	Description
	TERMINAL_SUPPORT	(default: 1)
Interactive prompt on serial	TERMINAL_SERIAL_SUPPORT	(default: 1)
Read up to N bytes, limits the total command size	TERMINAL_SERIAL_BUFFER_SIZE	(default: 128)
Specific port to use (must support both RX and TX)	TERMINAL_SERIAL_PORT	(default: 1)
	TERMINAL_MQTT_SUPPORT	Add support for MQTT topic that handles terminal commands. Depends on MQTT_SUPPORT (default: 0)
	TERMINAL_WEB_API_SUPPORT	Add support for HTTP endpoint that handles terminal commands. Depends on WEB_SUPPORT (default: 0)
termWebApiPath	TERMINAL_WEB_API_PATH	HTTP Path for TERMINAL_WEB_API_SUPPORT command line endpoint (default: /api/cmd)

Commands

Available commands as of 1.15.0-dev (the actual list of available commands will depend on the built-in functionalities of your specific image):

command	description
commands	Lists available commands
crash	Shows stack dump from last crash
del <key>	Deletes setting from EEPROM. Built-in
eeprom	Dumps some useful information about EEPROM
eeprom.commit	Trigger EEPROM.commit() (in case firmware is configured without auto-save functionality)
eeprom.dump [<ascii>]	Dumps EEPROM contents to console (pass a 1 to print ASCII characters)
erase.config	Tries to reset SDK config and restarts the board
factory.reset	Deletes all settings from EEPROM and resets the device
get <key>	Shows the value a the given setting
gpio <id> [<value>]	Gets or sets the GPIO #id state
heap	Shows free heap
help	Lists available commands (alias for "commands")
info	Shows info about the device, the firmware and the WiFi connection
keys	Lists the setting keys stored in EEPROM.
reload	Applies committed changes
reset	Resets board
reset.safe	Resets board into safe mode (only WiFi AP, serial and OTA will be enabled)
set <key> <value>	Changes the value of the given setting
uptime	Shows the current uptime in seconds
flash.dump [<sector>]	Dumps flash sector contents to console

You can read about some of the built-in commands at Embedis wiki.

Some modules implement their own terminal commands:

Command	description
OTA
ota <url>	Downloads a firmware image from the give URL and updates the board
LIGHT
brightness <value>	Sets RGB brightness (only for lights)
channel <id> <value>	Sets value for channel #id (only for lights)
color <value>	Sets RGB color (only for lights)
kelvin	Sets the temperature color in Kelvin (only for lights)
mired	Sets the temperature color in Mired (only for lights)
WiFi
wifi.ap	Disconnect and create an access point
wifi.sta	Disconnect and try to connect to configured networks
wifi.reset	Reconnects to the WiFi using current settings
wifi.scan	Scans for WiFi networks around and shows info
MQTT
mqtt.reset	Reconnects to the MQTT broker using current settings
RFBRIDGE
rfb.write <id>	Send HEX-encoded message as-is to the device
learn <id>	Learn RF code for relay ID
forget <id>	Forget previously learned RF code
NOFUSS
nofuss	Forces a check against NoFUSS server
HOME ASSISTANT
ha.clear	Clear retained message for MQTT Discovery in Home Assistant
ha.config	Output Home Assistant configuration code
ha.send	Send message for MQTT Discovery in Home Assistant
LIGHTFOX
lightfox.learn	Start learning RF code
lightfox.clear	Forget previously learned RF code
TUYA
tuya.show	Show discovered configuration (when there are no tuyaSwitchN or tuyaChannel# set)
tuya.save	Save discovered configuration into tuyaSwitchN and tuyaChannelN DP association keys
lightfox.clear	Forget previously learned RF code

Settings

The get, set and del commands let you query, modify or delete configuration settings. Most of those settings can be changed from the web interface.

Settings are stored in EEPROM. They persist across reboots and they survive firmware or filesystem updates (both wired or OTA) unless you change the flash layout.

This is a list of current settings with description and default values. '#' means a number starting from 0.

Key	Description	Possible values	Default value
ALEXA
alexaEnabled	Is Alexa integration enabled?	0 (no) or 1 (yes)	1 (yes)
API
apiEnabled	Should REST API be enabled?	0 (no) or 1 (yes)	0 (no)
apiKey	API Key required for all REST API requests	HEX string	(auto-generated when saving from WebUI for the first time)
apiRealTime	Should the API should respond with real time values or filtered ones?	0 (no) or 1 (yes)	0 (no)
DOMOTICZ
dczEnabled	Should Domoticz be enabled?	0 (no) or 1 (yes)	1 (yes)
dczTopicIn	Topic to send values to Domoticz		domoticz/in
dczTopicOut	Topic where Domoticz sends commands to		domoticz/out
dczRelayIdx#	IDX in Domoticz for the n-th relay (both to get and set value)	An integer, 0 or empty to disable report	0
dczMagnitude#	IDX in Domoticz for the n-th magnitude (type "magnitudes" for a list of available magnitudes)	An integer, 0 or empty to disable report	0
GENERAL
adminPass	Password to access web interface, connect to the device in AP mode or perform OTA updates	String of at least eight characters (letters, numbers or the underscore) with at least one number, one lowercase and one uppercase letter	fibonacci
hostname	Hostname for the device, device would be accessible at http://hostname.lan	A string	ESPURNA_XXXXXX (where XXXXXX are hex encoded bytes of Chip ID)
board	Board id (this setting is meant for future identification)
boardName	Board id (this setting is used to identify the board on OTA updates)
cfg	Configuration version (this setting is meant for future identification)
loopDelay	Delay in milliseconds at the end of the main loop (reduces power consumption but also responsiveness)	A number equal or greater than 0	10
HOME ASSISTANT
haEnabled	Home Assistant MQTT discovery feature enabled	0 (no) or 1 (yes)	1 (yes)
haPrefix	Home Assistant MQTT prefix	A string	homeassistant
INFLUXDB
idbDatabase	InfluxDB database name	A string
idbEnabled	Enable sending data to InfluxDB	0 (no) or 1 (yes)	0 (no)
idbHost	InfluxDB database host	A string
idbPassword	InfluxDB database password	A string
idbPort	InfluxDB database port	An integer	8086
idbUsername	InfluxDB database username	A string
MQTT
mqttClientID	MQTT client ID	A string	Same as default hostname
mqttEnabled	Enable sending MQTT messages	0 (no) or 1(yes)	1 (yes)
mqttFP	Fingerprint for SSL server	A 20 hex values separated by ':'
mqttGetter	MQTT getter suffix	A string with a leading slash
mqttGroup#	Synchronization group for the n-th relay	An MQTT topic
mqttGroupColor	Synchronization group for the color	An MQTT topic
mqttGroupInv#	Logic for the synchronization group for the n-th relay	0 (same) or 1(inverted)	0 (same)
mqttKeep	Keep alive time in seconds	A number greater than 10	30
mqttPassword	Password to connect to the MQTT broker	A string
mqttPort	Port the MQTT broker is listening to	A number	1883
mqttQoS	QoS level for MQTT messages and subscriptions	0 (at most one), 1 (at least one) o 2 (one and only one)	0 (at most one)
mqttRetain	Retain flag for messages	0 (don't retain) or 1 (retain)	1 (retain)
mqttServer	Address of the MQTT broker	An IP, hostname or empty to disable MQTT connection
mqttSetter	MQTT setter suffix	A string with a leading slash	/set
mqttTopic	Root topic for all MQTT topics of this device	A string, {hostname} will be replaced by the current hostname	{hostname}
mqttUseJson	Whether to group messages in a JSON format	0 (no) or 1(yes)	0 (no)
mqttUser	User to connect to the MQTT broker	A string
mqttUseSSL	Whether to connect using TLS/SSL	0 (no) or 1(yes)	0 (no)
LIGHT
brightness	Brightness value	0 to 255	255
ch#	Value for the n-th channel	0 to 255	0
useColor	Use first 3 channels for RGB	0 (no) or 1 (yes)	1 (yes)
useGamma	Use gamma correction for color channels	0 (no) or 1 (yes)	0 (no)
useWhite	Use white channel if all 3 RGB have the same value	0 (no) or 1 (yes)	0 (no)
useCSS	Use CSS (#FF0000) or comma separated values (255,0,0) for color reporting	0 (CSV) or 1 (CSS)	1 (CSS)
useRGB	Use first three channels as color channels (only if light has at least 3 ch)	0 (no) or 1 (yes)	1 (yes)
useTransitions	Use color transitions	0 (no) or 1 (yes)	1 (yes)
NOFUSS
nofussEnabled	Enable checking updates against a NoFUSS server	0 (no) or 1(yes)	0 (yes)
nofussInterval	Milliseconds between NoFUSS update checks	Number	3600000
nofussServer	NoFUSS service URL	URL, empty to disable NoFUSS
NTP
ntpDST	Enable daylight saving time	0 (no) or 1 (yes)	1 (yes)
ntpOffset	Time offset from UTC in minutes	Number	60
ntpRegion	NTP region to use for DST calculation	0 (Europe) or 1 (USA)	0 (Europe)
ntpServer#	NTP server to use (up to 3 different servers)	A string
ntpTimeout	NTP response timeout in milliseconds	Number	1000 (NTP_TIMEOUT)
RFBRIDGE
rfbOFF#	Code to turn OFF the n-th device	A string
rfbON#	Code to turn ON the n-th device	A string
TELNET
telnetSTA	Enable telnet when connected to a router (STAtion mode)	0 (no) or 1 (yes)	0 (no)
telnetAuth	Ask for admin password	0 (no) or 1 (yes)	1 (yes)
THINGSPEAK
tspkEnabled	Enable reporting values to Thingspeak platform	0 (no) or 1 (yes)	0 (no)
tspkKey	API Key for the channel to send data to	A string provided by Thingspeak
tspkMagnitude#	Field number for n-th magnitude	The field number to report to (1 to 8) or 0 to disable reporting	0
tspkRelay#	Field number for n-th relay	The field number to report to (1 to 8) or 0 to disable reporting	0
WEB
webPort	Port to listen to HTTP requests	An integer	80
wsAuth	Use WebSocket authentication	0 (no) or 1 (yes)	1 (yes)
WIFI
dns#	DNS for the n-th WiFi network when using static IP	IP
gw#	Gateway for the n-th WiFi network when using static IP	IP
ip#	Static IP for the n-th WiFi network	IP
mask#	Netmask for the n-th WiFi network when using static IP
pass#	Password of the n-th WiFi network	String
ssid#	SSID or name of the n-th WiFi network	String
wifiScan	Perform a scan to find best WiFi network	0 (no) or 1 (yes)	1 (yes)
wifiSleep	Set WiFi sleep mode (see Core source)	0 (WIFI_NONE_SLEEP), 1 (WIFI_LIGHT_SLEEP) or 2 (WIFI_MODEM_SLEEP)	0 (No sleep)
PZEM004T
pzemAddr	PZEM IP address(es)	String	PZEM004T_ADDRESS (also see wiki)
TUYA
tuyaFilter	DP type to filter incoming messages from (for every DP found)	Number	Unset, see #2222
tuyaSwitch#	DP number of the #'th switch	Number
tuyaChannel#	DP number of the #'th channel	Number
tuyaDebug	Enable extra-verbose debug logging	Boolean	1 (enabled)

Usage

You can configure your WiFi connection without web interface through the terminal. For instance:

set ssid0 myhome
set pass0 mypass
wifi.reset