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