Introduction
This document briefly explains all relevant configuration commands supported by Regado devices, including syntax, parameters and command examples.
The document also contains a reference on how to interface with the devices using the MQTT protocol, e.g. reading device input values and controlling the device outputs.
Created: 30/08/2021
Last modified: 19/01/2025
Version: 8
Created by: Lukas D'Angelo
Valid for FW builds: 01/01/2025 - current
Basic Commands
help
The help or ? command shows a list of all commands supported by the current HA-EA platform.
Syntax
help
Parameters
None
Example
$ help
clear Clears the terminal screen
cp Copy a file
defaults Load default configuration
diagmode Diagnostic mode configuration commands
ethernet Ethernet interface configuration commands
hostname Set hostname of the system
httpdl Download a file from a server via HTTP
hw Hardware platform configuration commands
ip Internet protocol configuration commands
ls List directory content
md5sum Calculate the MD5 hash of a file
mkdir Create a directory
mqtt MQTT protocol configuration commands
mv Rename or move a file
nslookup Query DNS server
ntp NTP configuration commands
password Set management password of the system
ping Send ICMP ECHO_REQUEST to a remote host
print Print file content
rm Remove a directory entry
rmdir Remove a directory
restart Restart the system now
save Save running configuration to flash
show Show system parameters
startupimg Select firmware image to boot
telnet Telnet management configuration commands
username Set management user of the system
wifi WiFi interface configuration commands
Note: ? is also used to give hints about the syntax or options of a command.
$ ip ?
gateway Set the Default Gateway
nameserver Set the Nameserver for DNS Resolution
Clearing the terminal screen
The clear command clears the terminal screen.
Syntax
clear
Parameters
None
Example
$ clear
Loading default configuration
The defaults command loads the default system configuration.
Syntax
defaults
Parameters
None
Example
$ defaults
Info: Loading default configuration.
Note: defaults loads the default system configuration to RAM, use save to make it persistent.
Restarting the device
The restart command will restart the device.
Syntax
restart
Parameters
None
Example
$ restart
Info: System is restarting now.
Note: When executing restart, all device hardware states and any unsaved configuration will be lost.
Saving the configuration
The save command will write the running configuration to persistent memory.
Syntax
save
Parameters
None
Example
$ save
Info: Saving running configuration to flash.
Showing system parameters
The show command displays system configuration parameters and system status elements.
Syntax
show option
Parameters
| Option | Value | Description |
|---|---|---|
| config | - | shows running system configuration |
| custom-registers | - | shows the current values of the custom registers |
| diagmode | - | shows diagnostic mode settings |
| ethernet | - | shows ethernet interface parameters and information |
| hostname | - | shows system hostname |
| hw | - | shows hardware platform parameters |
| info | - | shows system hardware and software information |
| ip | - | shows system IP information |
| mqtt | - | shows MQTT protocol settings |
| password | - | shows system management password |
| username | - | shows system management user |
| telnet | - | shows telnet management settings |
| time | - | shows system time |
| wifi | - | shows WiFi interface parameters and information |
| wifi-networks | - | scans and shows local WiFi networks |
Example
$ show ip
Ethernet interface:
IP-address: 172.16.15.220 (autoconfiguration)
Subnet mask: 255.255.255.128
Default gateway: 172.16.15.129
IP-address of nameserver: 172.16.15.129
Management & Maintenance Commands
Diagnostic mode
The diagmode command is used to configure diagnostic message output and transmission behaviour.
Syntax
diagmode option value
Parameters
| Option | Value | Description |
|---|---|---|
| terminal | enable | enables printing diagnostic messages to the terminal |
| terminal | disable | disables printing diagnostic messages to the terminal |
| mqtt | enable | enables the generation of a json string containing diagnostic information which can be published over MQTT |
| mqtt | disable | disables the generation of a json string containing diagnostic information which can be published over MQTT |
Example
$ diagmode terminal enable
Note: diagmode mqtt is currently not supported, this configuration does not apply.
Listing directory content
The ls command shows the content of a directory.
Syntax
ls value
Parameters
| Option | Value | Description |
|---|---|---|
| - | path | path of the desired directory |
Example
$ ls
- 13/02/2024 21:52:32 1142 config.json
- 13/02/2024 21:48:44 372700 firmware.bin.gz
Removing a file
The rm command is used to remove a file. The removed file is irreversibly lost.
Syntax
rm value
Parameters
| Option | Value | Description |
|---|---|---|
| - | path | path of the desired file |
Example
$ rm config_backup.json
Removing a directory
The rmdir command is used to remove a directory. Only empty directories can be removed.
Syntax
rmdir value
Parameters
| Option | Value | Description |
|---|---|---|
| - | path | path of the desired directory |
Example
$ rmdir old_configs
Downloading a file over HTTP
The httpdl command is used to download a file from a server via HTTP.
Syntax
httpdl value_URL value_path
Parameters
| Option | Value | Description |
|---|---|---|
| - | URL | URL of the desired file to download (source) |
| - | path | local path of the downloaded file (destination) |
Example
$ httpdl http://10.0.10.9:8000/firmware.bin.gz /firmware.bin.gz
Calculating MD5 checksum of a file
The md5sum command is used to calculate the MD5 checksum of a file.
Syntax
md5sum value
Parameters
| Option | Value | Description |
|---|---|---|
| - | path | path of the desired file to check |
Example
$ md5sum firmware.bin.gz
8cd10cb9ba5b66e992674a003712af1f firmware.bin.gz
Calculating SHA256 checksum of a file
The md5sum command is used to calculate the SHA256 checksum of a file.
Syntax
sha256sum value
Parameters
| Option | Value | Description |
|---|---|---|
| - | path | path of the desired file to check |
Example
$ sha256sum firmware.bin.gz
8b43cf4f6a88d6e2181e510da763363520767e11f83af5dab15b4d3790ac2d66 firmware.bin.gz
Moving a file
The mv command is used to move or rename a file. The source file is irreversibly lost. Already existing files with the same dst_path are
overwritten.
Syntax
mv value_srcpath value_dstpath
Parameters
| Option | Value | Description |
|---|---|---|
| - | value_srcpath | source path of the desired file |
| - | value_dstpath | destination path of the desired file |
Example
$ mv config_backup.json config.json
Copying a file
The cp command is used to copy a file. Already existing files with the same dst_path are
overwritten.
Syntax
cp value_srcpath value_dstpath
Parameters
| Option | Value | Description |
|---|---|---|
| - | value_srcpath | source path of the desired file |
| - | value_dstpath | destination path of the desired file |
Example
$ cp config.json config_backup.json
Selecting the startup image
The startupimg command is used to upgrade the system firmware from file
Syntax
startupimg value
Parameters
| Option | Value | Description |
|---|---|---|
| - | path | path of the desired firmware image |
Example
$ startupimg /firmware.bin.gz
Note: This command is blocking, any local routine and operation on the system is halted. restart is required to apply the new firmware.
Setting the system hostname
The hostname command configures the system hostname.
Syntax
hostname value
Parameters
| Option | Value | Description |
|---|---|---|
| - | hostname | the hostname of the system |
Example
$ hostname Regado
Setting the system management password
The password command configures the password of the system management user.
Syntax
password option value
Parameters
| Option | Value | Description |
|---|---|---|
| plain-text | password | sets the user password and stores it in plain text |
| crypt | password | sets the user password and stores a SHA-256 hash of it |
Example
$ password crypt ultrasecurepassword
Info: System password set successfully.
Send ICMP ECHO_REQUEST packets
The ping command is used to send ICMP ECHO_REQUEST packets to a network host.
Syntax
ping value
Parameters
| Option | Value | Description |
|---|---|---|
| - | hostname | the desired hostname |
Example
$ ping 1.1.1.1
32 bytes from 1.1.1.1: time=9 ms ttl=57
32 bytes from 1.1.1.1: time=9 ms ttl=57
32 bytes from 1.1.1.1: time=8 ms ttl=57
32 bytes from 1.1.1.1: time=9 ms ttl=57
--- Ping statistics for 1.1.1.1 ---
Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approx. RTT min/avg/max = 8/8.75/9 ms
Printing files
The print command is used to print the file content to the terminal.
Syntax
print value
Parameters
| Option | Value | Description |
|---|---|---|
| - | path | path of the desired file to print |
Example
$ print ./config.json
Setting network time
The ntp command configures the parameters for the NTP clock synchronisatrion protocol.
Syntax
ntp option value
Parameters
| Option | Value | Description |
|---|---|---|
| server | hostname | sets the ntp server hostname or IP-address |
| timezone | timezone | sets the system timezone in POSIX format |
Example
$ ntp server it.pool.ntp.org
$ ntp timezone CET-1CEST,M3.5.0,M10.5.0/3
Note: use POSIX timezones strings as cheat-sheet.
Setting the system management username
The username command configures the username of the system management user.
Syntax
username value
Parameters
| Option | Value | Description |
|---|---|---|
| - | username | the username of the system management user |
Example
$ username root
Remote management
The telnet command configures the telnet management parameters.
Syntax
telnet option value
Parameters
| Option | Value | Description |
|---|---|---|
| mgmt | enable | enables telnet management |
| mgmt | disable | disables telnet management |
| port | port | sets the TCP-port for telnet management |
Example
$ telnet mgmt enable
$ telnet port 23
Note: This command exposes the shell of the device to TCP-port 23.
MQTT Commands
MQTT connection commands
The mqtt command configures the MQTT protocol parameters and MQTT publishing behaviour.
Syntax
mqtt option value
Parameters
| Option | Value | Description |
|---|---|---|
| server | hostname | configures the IP-address or hostname of MQTT server |
| secure-connection | enable | use TLS as transport protocol for MQTT |
| secure-connection | disable | use TCP as transport protocol for MQTT |
| server-cert | - | invokes transmission mode for sending the x509 server certificate for secure connection |
| port | port | configures the TCP port for MQTT of the server |
| username | username | configures the MQTT username |
| password | password | configures the MQTT password |
| topic-base | topic | configures the customizable part of the subscribe and publish topic for the relays |
| send-interval- analog-inputs | interval | configures the send interval for analog input values in milliseconds |
| send-interval-sensor | interval | configures the send interval for sensor data in milliseconds |
Example
Connecting to a server using TCP:
$ mqtt server 10.0.10.109
$ mqtt secure-connection disable
$ mqtt port 1883
$ mqtt username ha-ea
$ mqtt password 83re&34!
Setting the base topic (root path used for all device resources):
mqtt topic-base Regado
Publishing the values of the sensors and the values of the analog inputs every 10 seconds:
$ mqtt send-interval-sensor 10000
$ mqtt send-interval-analog-inputs 10000
Note: A interval of 0 will disable periodic sending.
Network Interface Commands
Ethernet interface
The ethernet command is used to enable or disable the ethernet interface.
Syntax
ethernet option
Parameters
| Option | Value | Description |
|---|---|---|
| enable | - | enables the ETHERNET interface (layer 3 only) |
| disable | - | disables the ETHERNET interface (layer 3 only) |
| ip-address | ip-address | configures the IP-address of the ETHERNET interface, dhcp for IP auto-configuration |
| netmask | netmask | configures the network mask of the ETHERNET interface |
Example
Enabling the ETHERNET interface and using DHCP autoconfiguration:
$ ethernet enable
$ ethernet ip-address dhcp
Note: Static netmask configuration of these values is ignored if IP autoconfiguration is enabled.
IP settings
The ip command configures the IP-address of the system, the default gateway and the DNS server.
If ETHERNET is supported by the platform, the configurations applies to both the WiFi and ETHERNET interface.
The interfaces cannot be used simultaneously.
Syntax
ip option value
Parameters
| Option | Value | Description |
|---|---|---|
| gateway | ip-address | configures the IP-address of the default gateway |
| nameserver | ip-address | configures the IP-address of the DNS server |
Example
Setting DNS server address:
$ ip nameserver 1.1.1.1
Note: Any static configuration of gateway and nameserver is ignored if IP autoconfiguration is enabled on at least one of the interfaces.
WiFi interface
The wifi command is used to configure the WiFi interface.
Syntax
wifi option value
Parameters
| Option | Value | Description |
|---|---|---|
| enable | - | enables the WiFi interface and disables the ETERNET interface if present |
| disable | - | disables the WiFi interface and anables the ETERNET interface if present |
| station-ssid | SSID | configures SSID of the WiFi network to be connected |
| station-psk | PSK | configures PSK of the WiFi network to be connected |
| ip-address | ip-address | configures the IP-address of the WiFi interface, dhcp for IP auto-configuration |
| ip-netmask | netmask | configures PSK of the WiFi network to be connected |
| soft-ap-mode | enable | enables the soft AP feature of the system for management |
| soft-ap-mode | disable | disables the soft AP feature of the system for management |
| soft-ap-ssid | SSID | configures SSID of the soft AP feature |
| soft-ap-psk | PSK | configures the PSK of the soft AP feature |
Example
Enabling the WiFi interface:
$ wifi enable
Setting up the WiFi network and using DHCP for IP-address configuration:
$ wifi station-ssid WAP_INT
$ wifi station-psk ultrasecurepsk
$ wifi ip-address dhcp
HW Platform Commands
Setting hardware platform parameters
The hw command is used to configure the hardware platform.
Syntax
hw option value(s)
Parameters
| Option | Value | Description |
|---|---|---|
| relay-count | INT | number of relays to control on the device or stack |
| one-wire-scan | - | initializes and scans the 1-Wire BUS for new sensors |
| set-custom-register | index value | sets the value of a custom register with a given index |
| set-digital-output | index value | sets the value of a digital output with a given index |
| io-passthrough-mode | disable | disables the I/O passthrough (for selected models only) |
| io-passthrough-mode | direct | sets direct I/O passthrough (for selected models only) |
| io-passthrough-mode | toggle | sets I/O passthrough mode to toggle (for selected models only) |
Example
Required command to make outputs of a HA-EA-S platform work:
$ hw relay-count 8
Note: For a stack configuration, the total number of relays has to be set.
If we want to turn on the digital output with index 6:
$ hw set-digital-output 6 1
Note: For digitital outputs, the value 0 turns the output off, any other value turns it on.
If we want to directly passthrough the state of an input to the corresponding output, we set:
$ hw io-passthrough-mode direct
If we want to toggle the output if the state of an input changes, we set:
$ hw io-passthrough-mode toggle
Note: I/O passthrough is only available on models with inputs and outputs.
API Reference
The MQTT API of Regado devices exposes the following resources:
- Digital outputs - if present, publish and subscribe
- Digital inputs - if present, publish only
- Analog inputs - if present, publish only
- Values of 1-wire sensors - if present, publish only
- Custom Registers - a set of 32 bit registers used to interface with local routines on the system, subscribe only
All resources use static, predifined paths (topics), but the root of the path can be specified with the command mqtt topic-base <base-topic>,
where <base-topic> is an arbitrary string.
Digital Outputs
In order to get commands to set digital outputs, the devices subscribes to the following topics:
<base-topic>/control/outputs/digital/0
<base-topic>/control/outputs/digital/1
...
<base-topic>/control/outputs/digital/N
where N+1 is the digital output count supported by the current hardware.
An output is set by publishing the value 0 or 1 to the desired topic. The output will immediately apply the desired value.
In order to emit the current state of a digital output, the device publishes the according values using the following topics:
<base-topic>/state/outputs/digital/0
<base-topic>/state/outputs/digital/1
...
<base-topic>/state/outputs/digital/N
Note: The device only publishes the state of a digital output only after establishing the MQTT connection and when its state changes.
Digital Inputs
In order to emit current state of digital inputs, the device publishes the according input state using the following topics:
<base-topic>/state/inputs/digital/0
<base-topic>/state/inputs/digital/1
...
<base-topic>/state/inputs/digital/N
where N+1 is the digital input count supported by the current hardware.
Note: The device only publishes the state of a digital input after establishing the MQTT connection and on change. The state of a digital input can be 0or 1.
Analog Inputs
In order to emit current state of analog inputs, the device publishes the according input value using the following topics:
<base-topic>/state/inputs/analog/0
<base-topic>/state/inputs/analog/1
...
<base-topic>/state/inputs/analog/N
where N+1 is the analog input count supported by the current hardware.
Note: The device only publishes the state of a digital input after establishing the MQTT connection and periodically
with a period specified with the command mqtt send-interval-analog-inputs <interval>. The value type of an analog input is an 32bit unsigned integer.
1-wire Sensors
In order to emit current current value of sensors present on the 1-wire bus, the device publishes the according value using the following topics:
<base-topic>/state/bus/1-wire/<ADDR-0>
<base-topic>/state/bus/1-wire/<ADDR-1>
...
<base-topic>/state/bus/1-wire/<ADDR-N>
where N+1 is the amount of sensors currently present on the 1-wire bus and <ADDR-X> is the static address of the sensor.
Note: The device publishes the states periodically with a period specified with the command mqtt send-interval-sensor <interval>. The value is rounded to one
decimal place.
Determining the Resources
In order to get the specific topics of the resources on a device, the command show hw is used. We get (exemplary):
$ show hw
Digital output count: 10
+----+-------+
| ID | VALUE |
+----+-------+
| 0 | 0 |
| 1 | 0 |
| 2 | 1 |
| 3 | 0 |
| 4 | 0 |
| 5 | 1 |
| 6 | 0 |
| 7 | 0 |
| 8 | 1 |
| 9 | 0 |
+----+-------+
Digital input count: 6
+----+-------+
| ID | VALUE |
+----+-------+
| 0 | 0 |
| 1 | 0 |
| 2 | 0 |
| 3 | 0 |
| 4 | 0 |
| 5 | 1 |
+----+-------+
Analog input count: 8
+----+-------+
| ID | VALUE |
+----+-------+
| 0 | 382 |
| 1 | 375 |
| 2 | 614 |
| 3 | 614 |
| 4 | 614 |
| 5 | 613 |
| 6 | 615 |
| 7 | 610 |
+----+-------+
1-Wire device count: 3
+----+-------------------+---------+
| ID | ADDRESS | VALUE |
+----+-------------------+---------+
| 0 | 401192D5C535828 | 55.5 |
| 1 | B101192D9311D128 | 57.0 |
| 2 | 101192D43BA8528 | 8.5 |
+----+-------------------+---------+
Note: This may be useful to obtain all the topics according to the definitions above for Regado Model H1.