Skip to content

Operational Commands

Operational commands are strings of text with a predetermined format. They are used to set up the device at runtime and can be received from different locations. For example the CLI module uses a Serial/UART connection to receive operational commands. The bluetooth module is also used to send operational commands from an external device (smartphones). Operational commands can also be created from the web server and received through the Net module.

Life cycle of a command

Usually a command will be created from an external device and a communication port will be used to receive the command.

When a command is received, it will first be validated for proper formatting and then executed.

Finally a response is returned to the external device to inform whether the command was executed correctly or not.

Life cycle of command diagram

Command Format

Commands are text strings with a very simple format:

$123456789|8:10;40:1|9#

There are two start ($) and end (#) characters. The string is separated into three sections: command id, command body and body size

123456789 Command ID. The client is responsible for creating a unique identifier for the command. The response will contain this identifier.
8:10;40:1 Command body. Contains a list of properties:value separated by semicolon (;)
9 Body size in bytes

Command ID

The command id must be generated by the client that generates the command. Rhomb.IoT does not internally store any list of IDs or perform any special validation of the ID. It is used in the responses to commands, so that the client can better identify that the command has been successfully executed.

Two external devices could generate the same ID and it would not be a problem, each device will receive its response through the channel with which it has initiated the communication.

Command Body

The body of the message consists of a list of properties:value separated by semicolon.

In the previous example we can see that there are two properties, 8:10 and 40:1. The property 8 configures the global variable Tick1, which contains the time interval in seconds (10) for sending information to the server, and the property 40 saves the configuration in persistent memory to be maintained after a reset.

Command Size

It is used for the purpose of validating that no information has been lost during the transmission of the command, and that the received body is the same size as when it was created.

Todo

In the future a better validation with CRC code should be implemented.

Command Properties

There are more than 50 properties that allow you to change the configuration and behavior of the device.

Property Name Value Info
0 reserved
1 Enable/Disable Deep Sleep 1/0
2 Enable/Disable Sleep 1/0
3 reserved
4 reserved
5 Set minimum VBAT before sleep >=3600 / <=4100 / 0 disable Minimum vbat value in millivolts before enter in sleep mode
6 Set minimum VIN before sleep >=6000 / <=70000 / 0 disable Minimum vin value in millivolts before enter in sleep mode
7 Set minimum VSYS before sleep >=4000 / <=5200 / 0 disable Minimum vsys value in millivolts before enter in sleep mode
8 Tick Interval 1 number in seconds / 0 disable Time interval for Tick1. It is responsible for setting the time interval for sending data to the server. It accepts a value in seconds, for example if we want to transmit every minute we will indicate the number 60->8:60
9 Tick Interval 2 number in seconds / 0 disable Time interval for tick2. Internally Rhomb.IoT does not give any use to this timer, but it can be useful in multiple applications.
10 Set Keep TCP Open 1/0 In case of true (1) the net module will keep the TCP connection to the remote server always open.
11 Set Use Temperature 1/0 Enables the transmission of temperature to the web server. A temperature sensor must be enabled in conf-user.h.
12 Set Use Atmospheric Press. 1/0 Enables the transmission of atmospheric pressure to the web server. An atmospheric pressure sensor must be enabled in conf-user.h.
13 Set Use Gas 1/0 Enables the transmission of gas to the web server. A gas sensor must be enabled in conf-user.h. Applies to all gas sensors: IAQ, VOC and MQx
14 Set Use Humidity 1/0 Enables the transmission of humidity to the web server. A humidity sensor must be enabled in conf-user.h.
15 reserved
16 reserved
17 Enable/Disable GPS Modem 1/0 A system reset is required, please use save[40] and reset[41] properties after change any GPS property.
18 Set Use GPS Geolocation 1/0 Enable the transmission of latitude/longitude to the server
19 Set Use GPS Altitude 1/0 Enable the transmission of altitude to the server
20 Set Use GPS Speed 1/0 Enable the transmission of speed (sog) to the server
21 Set Use GPS Orientation 1/0 Enable the transmission of orientation (cog) to the server
22 Set Use GPS Sats 1/0 Enable the transmission of number of satellites to the server
23 Set Use GPS HDOP 1/0 Enable the transmission of HDOP (GPS signal quality) to the server
24 Set Use GSM Signal 1/0 Enable the transmission of GSM Singal quality to the server
25 Set Use Local Time 1/0 Enable the transmission of local time to the server
26 Set Use GSM Based Geolocation 1/0 not implemented When enabled it allows to obtain the geolocation using the GSM networks when GPS is not available.
27 Set transmit with SMS 1/0 not implemented Transmit data using SMS messages, not remote TCP Server.
28 Set SMS number String(+34627555555) not implemented SMS Phone Number to transmit when "transmit with SMS" is enabled
29 reserved
30 reserved
31 Use Battery 1/0 Enable/Disable transmission of all the battery values
32 Use VBAT 1/0 Enable/Disable transmission of VBAT to the server
33 Use VSYS 1/0 Enable/Disable transmission of VBAT to the server
34 Use VIN 1/0 Enable/Disable transmission of VBAT to the server
35 Set sim card APN String Set the APN for the sim card
36 Set sim card APN User String Set the APN user for the sim card
37 Set sim card APN Pass String Set the APN pass for the sim card
38 Set remote server IP/Domain String Set the IP or domain domain for the TCP remote server 1. It will be applied instantly, without reset.
39 Set remote server IP/Domain Number Set the port number for the TCP remote server 1
40 Save the current configuration 1 Makes the current settings permanent (remains after a reset). Must be the last property of the string, for example: 8:60;11:1;14:1;40:1 (four properties, save is last)
41 MCU Software Reset 1 Execute a system reset via software. No matter in what order the property is included in the body, all the properties of the command will always be executed first before resetting
42 Set master GPIO Status 1/0 1 to set GPIO as HIGH, 0 for LOW. The master GPIO is configured in conf-user.h
43 Enable GPIO Number Set a GPIO as HIGH. For example: 43:25 = digitalWrite(25, HIGH)
44 Disable GPIO Number Set a GPIO as LOW. For example: 44:25 = digitalWrite(25, LOW)
45 Set GPIO as INPUT Number Set GPIO direction as INPUT. For example: 45:25 = pinMode(25, INPUT)
46 Set GPIO as OUTPUT Number Set GPIO direction as OUTPUT. For example: 45:25 = pinMode(25, OUTPUT)
47 reserved
48 Write to SERIAL_DEBUG String Sent string to serial debug. It uses println().
49 Write to SERIAL_S1 String Sent string to serial s1. It uses println().
50 Write to SERIAL_CLI String Sent string to serial cli. It uses println().
51 Write to SERIAL_S2 String Sent string to serial s2. It uses println().
52 Set Use Accelerometer 1/0 Enable/Disable accelerometer functions
53 Set WiFi SSID String Set WiFi SSID (Name). Maxlength is defined in macro BUFFER_SIZE_WIFI_NAME on conf-user.h
54 Set WiFi Password String Set WiFi password. Maxlength is defined in macro BUFFER_SIZE_WIFI_NAME on conf-user.h
55 reserved
56 Sleep now 1 Put the microcontroller in sleep mode. Sleep time is defined in conf-user.h.
57 Locker: Unlock door 1-16 Unlock the door with the given number
58 Locker: Unlock all 1 Unlock all doors
59 reserved
60 reserved

Receiving Operational Commands

CLI Module

It allows to receive operational commands through a Serial/UART connection. Usually the device is connected to a USB port of a PC, and from there a serial communication is initiated to send the commands.

(More Info)[/users/cli/]

Bluetooth Modem

The bluetooth modem of the SIM868 or ESP32 module can be used to initiate a serial communication (SPP) from a smartphone or other device.

(More Info)[/users/bluetooth/]

Web Dashboard

From our web dashboard you can send operational commands to a device or group of devices. There are widgets for sending specific commands and a command creation panel where all available properties are displayed.

(More Info)[/users/web-dashboard/]

Comments