Communication Protocol
Rhomb.IoT uses a custom communication protocol based on the exchange of text strings between client and server.
In order to transmit data to the server, the device has to create what we call a "message", a text string with a predetermined format like this:
1104666880|s|vs:4916$vi:11446$
It is divided into three parts, the symbol | is used to separate each part:
| 1104666880 | Device ID | The server needs this value to recognize and authorize the device |
| s | Type of message | There are 3 possible values: s (sensing), l (login) and a (alert). The first message to sent to the server after a MCU reset should be a login message. After login the system continues sending messages with type sensing. If is required the system can create an alert message |
| vs:4916vi:11446 | Body of the message | A body can contain multiple properties, each one separated with a $. Each property may have a value. The server can recognize a limited number of properties, please see the table "available properties" |
Device ID
The server needs to know the device ID to grant access. Previously a device has to be registered using the M2M System Source web application.
There are two ways to set an ID, automatically or manually.
Obtain ID automatically
It is possible to set de device ID automatically using the communication modem. For example with ESP32 or ESP8266 Rhomb.IoT uses the MAC address to generate a hash with only numbers. This is also done with the SIM800/SIM868 modem, but here the internal IMEI number of the modem itself is used as the device ID.
To obtain the ID automatically, you will have to set up the DEVICE_ID macro with an empty string.
#define DEVICE_ID ""
Set ID manually
To set the ID manually simply set the value on the macro:
#define DEVICE_ID "0000000001"
Usually it is not recommended to set the ID manually and it is preferable to use the automatic mode. By using the MAC or IMEI addresses of the modems we ensure that our device has a unique address. Using the manual mode we run the risk of making a human error and have several devices with the same ID, so use the manual mode only if you have a very small fleet of devices or for testing purpose.
More info about Device ID in Module Core/Device
Message types
Login Messages
- Code:
l
This is the first message we send to the server. The device performs a login to verify that it has access to the service and can start sending sensing messages.
Sensing messages
- Code:
s
The sensing messages contain information from sensors and actuators. The amount of information added will depend on the configuration in `conf-user.h', depending on how many modules we have activated.
Alert Messages
- Code:
a
Currently the creation of alert messages is in disuse, but it is expected that this will change in the future and that Rhomb.IoT will have the capacity to generate special messages in response to special situations.
In any case, the web platform allows the creation of all kinds of alerts, for example to check that the values of a sensor are within a range or to create GPS geofence zones. This web alert system uses the information received with the sensing messages
In case you have a special need there is also the possibility to extend Rhomb.IoT to create your own messages.
Body of the message
The message body contains a list of properties and values. Rhomb.IoT is a modular system, messages will have more or less information depending on the active modules.
The messages can contain data from environmental sensors, GPS modems, internal voltages, accelerometer, GPIOS status and many other things. This is the current list of available properties:
| Property:value | Info |
|---|---|
| vi:11821 | Value of VIN. It is the external voltage supplied to the board. |
| vb:3928 | Value of VBAT. Internal battery, usually a 3.7v lipo |
| vs:4876 | Value of VSYS. Also known as VUSB, should have a value near 5v if USB cable is connected to the rhomb.io hardware. |
| loc: 34.123123,-0.192913 | Geolocation. An array of two float, first for latitude, second longitude. |
| alt: 495 | Geolocation. An array of two float, first for latitude, second longitude. |
| sog:82 | Geolocation. Movent speed in kn/h. |
| cog:127 | Geolocation. Movement orientation, a value between 1 and 359 |
| sats:10 | Number of GPS sats used to get the gps geolocation |
| hdop:0.9 | Quality of the GPS signal |
| gsm:22 | Quality of the GSM network, a value between 1 (poor) and 30 (excelent) |
| gloc: 34.12,-0.19,500 | Geolocation using GSM network. An array with 3 values: lat, lon and margin of error in meters |
| temp:22.5 | Value of temperature in centigrade |
| humi:70 | Relative humidity percentage |
| press:1291 | Atmospheric pressure in millibars |
| voc:30 | Value of air quality. Usually with a CCS811 gas sensor. |
| iaq:30 | Value of air quality. Usually with a BME680 using the BSEC driver from Bosch. |
| mqX:30 | Any of the popular MQ gas sensors, replace the X with the number of sensor, for example MQ5 |
| fuel:20 | Percentage of fuel available in any vehicle |
| rpm:2500 | Revolutions per minute of any vehicle |
| tmpr:1 | Tamper protection alert. If the device has an anti-tamper security system, this property will be 1 in the case that this system has been compromised. |
| vbra:1 | Vibration alert. If the device has a vibration detection system this property will be 1 in case vibrations are detected. |
GPIO Status
The status (HIGH/LOW) of any GPIO can be transmitted using his pin number and the keyword "io". For example, to transmit the value of the GPIO 9:
io9:1
or
io9:0
Where 1 is status HIGH or 0 LOW
Multiple GPIOS are also possible:
io9:0$io10:1$io11:1$io12:0
Analog GPIOS
Please see the ADC module.