Here is an alphabetical list of commands that can be entered via the serial port or the Web console. With the exception of four commands, config, help, restart and status, these commands are designed to modify the user settable configuration settings.

In all cases but for the four exceptions enumerated above, the commands report the associated settings or data if entered with no parameter. The output of each command is done via the logging facility. Messages which report the value of settings will be visible in a logging facility showing messages with level log or higher. The command interpreter also emits some ERR level messages when the user enters invalid data, and some debug level messages that were helpfull in developing the module.

ap - manage the access point.

Syntax: ap [-d|-x] | [<suffix> [<pswd>]]
Example: ap 5

• -d: Use the default values (as defined in user_config.h).
• -x: Clears the access point SSID suffix and password.
• <suffix> [<pswd>]: Set the access point SSID suffix and optional password.

Notes:

1. The device will create a Wi-Fi access point when the connection to the Wi-Fi network is lost for more than 5 minutes (see the time command). When a connection to the Wi-Fi network is restored, the access point is automatically brought down.
2. The access point web interface is used to enter the Wi-Fi network credentials and, optionally, the wifi switch static IP address.
3. The access point network name will be the "hostname" + "suffix" so the default value will be "KITCHENLIGHT-AP". The suffix to the right of the dash "-" can be modified with this command such as in the above example which sets to "KITCHENLIGHT-5".
4. If not optional password is specified after the suffix, then any existing access point password will be removed and the wireless network will be open to all.

apip - manage the access point IP address.

Syntax: apip [-d|-x] | [<ip> <mask>]
Example: apip 192.168.10.11 255.255.255.0

• -d: Use the default values as defined in user_config.h.
• -x: Remove the static IP address and use the ESP default values.
• <ip> <mask>: Set the static IP address of the device on the access point network and the subnet mask.

Notes:

1. When setting a static iP address the subnet mask must be set.
2. The invalid static IP address 0.0.0.0 is interpreted to mean the default IP address, 192.168.4.1 and mask 255.255.255.0 will be used.

config - manage the user-settable options.

Syntax: config [load|default|save [force]]
Example: config save force

• load: Loads any configuration previously saved into non-volatile storage (NVS - flash memory). If the NVS does not contain a valid configuration, then loads the default configuration, as set in user_config.h.
• default: Loads the default configuration, as defined in user_config.h.
• save [force]: Saves the currently used configuration into NVS. If the force parameter is present then the operation is done no matter if the configuration has changed or not. If the parameter is not present the configuration is saved only if there has been a change.

dmtz - manage the Domoticz server settings./dt>

Syntax: dmtz [-d] | [<host> [<port>]] ( [-x] | [-c <user> [<pswd>]]
Example: dmtz domus.local 8088 -c admin domoticz

• -d: Use the default (as defined in user_config.h).
• <host> [<port>]: Set the host name or IP address and optional TCP port.
• -x: Clears the Domoticz user name and password.
• -c <user> [<pswd>]: Set the Domoticz user name and optional password. NOT YET IMPLEMENTED

Note:

1. Currently, it is possible to set, clear or modify the Domoticz user account credentials, but these are not used when updating the virtual sensor values.
2. Starting with version 2023.1, Domoticz enforces logging into a user account with a password (default values: admin and domoticz respectively). However, it is possible to bypass this requirement when accessing the server from a trusted network, which is what must be done with the current version of this firmware. See the Security wiki.

help - displays the list of commands or or the syntax of individual commands.

Syntax: help [<command>]
Example: help config

• help: Displays all the available commands.
• help config: Displays config [load|default|save [force]] | [auto (off|on)] which is the syntax of config command.

idx - manage the Domoticz virtual device identity numbers.

Syntax: idx [-d] | [(switch|lux|temp) [<id>]]

• -d: Use the default id numbers (as defined in user_config.h).
• switch [nn] : Displays the switch id number used to update Domoticz or sets the id number to nn if that optional id number is given.
• lux [nn] : Displays the light sensor id number used to update Domoticz or sets the id number to nn if that optional id number is given.
• temp [nn] : Displays the temperature and humidity sensor id number used to update Domoticz or sets the id number to nn if that optional id number is given.

log - manage the log level of the logging facilities.

Syntax: log [-d] | [<facility>) [<loglevel>]]
Example: log webc ERR

• -d: Use the default log levels (as defined in user_config.h).
• <facility>: Log facility
  • uart: the serial console through the USB connector.
  • mqtt: the MQTT broker.
  • syslog: the remote syslog server (see command syslog).
  • webc: the Web console of the Web interface.
• <loglevel>: if defined, then log messages with a level greater or equal to the defined value will be shown on the specified facility.
  0. dbg - debug level
  1. inf - information level
  2. ERR - ERROR level
  The log level can be specified with the corresponding name or the number.

Note:

1. The log level names are case sensitive, so log webc err will raise an invalid value error.

mqtt - manage the MQTT broker.

Syntax: mqtt [-d] | [[<host> [<port>]] ( [-x] | [-c <user> <pswd>]] )
Example: mqtt 192.168.1.22 -c dmtz 123456789

• -d: Use the default (as defined in user_config.h).
• <host> [<port>]: Set the host name or IP address and optional port.
• -x: Clears the MQTT user name and password.
• -c <user> [<pswd>]: Set the MQTT user name and optional password.

Note:

1. Currently, it is possible to set, clear or modify the MQTT user account credentials, but these have yet to be tested.

name - manage the host and device names.

Syntax: name [-d] | [-h [<hostnanme>] | [-n [<device name>]]

• -d: Use the default values as defined in user_config.h.
• -h [<hostname>]: Displays the host name or optionally sets the host name to the given value.
• -n [<device name>]: Displays the host name or optionally sets the device name to the given values.

Notes:

1. A host name of a device connected to a network can contain only allowed characters: "a".."z", "A".."Z", "0".."9" or "-", but it must not start nor end with "-". Assume that the name is not case sensitive (Reference: https://en.wikipedia.org/wiki/Hostname)
2. The device name is displayed at the top of the Web interface. It can contain any UTF-8 encoded character and may contain up to 5 space delimited words.

restart - restart the device.

Syntax: restart [0|1|...|7]
Example: restart 7

Level	Actions before restarting
0	Saves the configuration if it has changed
1	Saves the configuration whether changed or not
2	Does nothing, not even saving any changes to the configuration
3	Sets a dynamic IP address and saves the configuration
4	Sets a dynamic IP address, clears the Wi-Fi credentials and saves the configuration
5	Restores the default configuration and then saves it.
6	Restores the default configuration, sets a dynamic IP address, and saves the configuration
7	Restores the default configuration, sets a dynamic IP address, clears the Wi-Fi credentials and saves the configuration

staip - manage the IP address of the device.

Syntax: staip [-d | -x ] | [<ip> <gateway> <mask>]
Example: staip 192.168.1.76 192.168.1.1 255.255.255.0

• -d: Use the default values as defined in user_config.h.
• -x: Remove the static IP address and obtain a dynamic IP address from the network DHCP server.
• <ip> <gateway> <mask>: Set the static IP address of the device, the IP address of the gateway and the subnet mask.

Notes:

1. The command is named staip for station IP not for static ip.
2. When setting a static iP address all three parameters must be set. Furthermore the IP address of the device must be on the same subnet as the IP address of the gateway.
3. The invalid static IP address 0.0.0.0 is interpreted to mean that a dynamic IP address will be obtained from the DHCP server. Use -x instead of setting that value.
4. Only IP version 4 is supported.
5. Any modification of the IP address and other parameters will take effect when a new Wi-Fi connection is established.
   • staip -x; restart will restart the device and ensure that it gets a dynamic IP address assuming the Wi-Fi credentials are valid.
   • staip 192.168.1.76 192.168.1.1 255.255.255.0; wifi NEW_NETWORK_SSID NEW_NETWORK_PASSWORD; restart will restart the device which will then attempt to connect to the NEW_NETWORK_SSID and set a static IP address. No verification is made to ensure that the specified IP address and gateway are valid.
6. See the wifi command.

status - display device information.

Syntax: status
Note:

1. Currently report the firmware version, the status of the Wi-Fi connection and the status of the MQTT connection.

syslog - manage the remote syslog server.

Syntax: syslog [-d] | [<ip> [<port>]]
Example: syslog 192.168.1.22

• -d: Use the default values as defined in user_config.h.
• <ip> [<port>]: IP address of the log server and the optional UDP port (default is defined in user_config.h, usually 1883).

Note:

1. A static IP version 4 address must be specified.

time - set time intervals.

Syntax: time [-d] | [(poll|update|http|ap) [<ms>]]
Example: time connect 5000

• -d: Use the default values as defined in user_config.h.
• poll [nn]: Reports the interval time (in milliseconds) between hardware polling of the button, or sets it to nn is the optional value is given.
• update [nn]: Reports the interval time (in milliseconds) between updates of the sensor data on the Web interface and in Domoticz.
• http [nn]: Reports the connection time out (in milliseconds), or sets it to nn if the optional value is given. This is time is for HTTP connections to Domoticz when updating the sensor data or the button state.
• ap [nn]: Reports the disconnection time (in milliseconds) before an access point is created or sets it to nn if the optional value is given. The access point is automatically created but not immmediately when the connection to the Wi-Fi network is lost. The access point is immediately closed when the Wi-Fi connection is established.

Note:

1. The connect time out value should be set in increments of 1000, because the resolution of that time is the second. The default value is 5 seconds (5000 ms).

topic - manage the MQTT topics.

Syntax: [-d] | [(log|cmd|pub|sub) [<topic>]]
Example: topic -d

• -d: Use the default values as defined in user_config.h.
• log [topic]: Reports the MQTT topic to which log messages are published or sets that topic if the optional topic is specified.
• cmd [topic]: Reports the subscribed MQTT topic to receive command messages or sets that topic if the optional topic is specified.
• pub [topic]: Reports the MQTT topic to which messages are published to update the state of Domoticz virtual devices or sets that topic if the optional topic is specified.
• sub [topic]: Reports the subscribed MQTT topic to Domoticz messages when the virtual switch is toggled or sets that topic if the optional topic is specified.

Note:

1. In the default log and cmd topics, %h% is a placehoder for the device hostname (see command name). So when topic cmd is "%h%/cmd" that translates to kitchenlight/cmd if the host name is kitchenlight.
2. The default sub topic (domoticz/out) corresponds to the default Flat Domoticz Publish Topic setting.

wifi - manage the Wi-Fi credentials.

Syntax: wifi [-d] | [<ssid> [<pswd>]]
Example: wifi my_home_wifi 12345678

• -d: Use the default values as defined in user_config.h.
• <ssid> [<pswd>]: Sets the Wi-Fi network name (ssid) and optional password.

Note:

1. The change will take effect when a new Wi-Fi connection is established.
2. Whenever a new Wi-Fi network is specified, it is important to verify the validity of the station IP address. If static, the IP address, gateway and subnet mask will most likely need to be changed.
• staip -x; wifi NEW_NETWORK_SSID NEW_NETWORK_PASSWORD; restart will restart the device and obtain a dynamic IP address once connected to the specified Wi-Fi network.
• staip 192.168.1.76 192.168.1.1 255.255.255.0; wifi NEW_NETWORK_SSID NEW_NETWORK_PASSWORD; restart will restart the device which will then attempt to connect to the specified Wi-Fi network and set the specified static IP address, no matter which subnet is used by the network. In other words, no verification is made to ensure that the specified IP address and gateway are valid.
3. Clearing the network name and password will mean that it will no longer