Terminal - xoseperez/espurna GitHub Wiki

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