Skip to content

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.

Comments