Modbus Protocol

This is the API description for the Modbus RTU protocol of the RS485 Extension.

An overview of products that are controllable over Modbus can be found here.

Protocol

The RS485 Extension uses Modbus RTU as the protocol on the RS485 interface.

High level configurations, such as baud rate, parity and stop bits can be done with the Brick Viewer and are stored on the EEPROM of the RS485 extension.

The protocol used on the RS485 Extension is modeled after the concept of a function call. A request packet is send by the RS485 master to the stack with RS485 Extension to trigger the execution of a function on a selected Brick or Bricklet. The stack answers with either a response (which can be the response of an older function call, a response to this function call or a callback) or a packet with an empty payload. If the answer by the RS485 slave was not empty, the RS485 master has to send an empty packet back (ACK).

Packet Layout

The Modbus protocol is based on packets transfered between a RS485 master and potentially many RS485 Slaves. Each packet consists of:

  • Modbus address as uint8 (1 byte),
  • Modbus function code as uint8 (1 byte),
  • Sequence number as uint8 (1 byte),
  • Payload (including UID, function ID, etc) and
  • Modbus CRC16 as uint16 (2 bytes)

The Modbus address is the address, that is stored in the EEPROM of the RS485 extension. It can be set with the Brick Viewer an it should be between 1 and 255. A message to a stack and responses from this stack will use this Modbus address.

As the Modbus function we use the public function code 100 in all packets (see Modbus Application Protocol V1.1b chapter 5 "Function Code Categories").

The Sequence number is incremented by the RS485 master and it is used to make sure that every request gets a response.

The Payload is a request or response packet as specified in the TCP/IP protocol.

Last but not least, the Modbus CRC16 is calculated for every packet, as specified in the Modbus RTU specification.

All data is represented in little endian. A bool value is represented by 1 byte; 0 is false, all other values are true. A float value is represented by 4 bytes in IEEE 754 format. A char value is represented by 1 byte in ASCII encoding.

A fixed size char array represents a string. If the string is shorter than the capacity of the array then the remaining space is filled with 0. In this case the contained string is null-terminated. In case that the string fills the whole array no null-terminator can be appended and the string is not null-terminated. Therefore, you cannot rely on strings being null-terminated.

Requests and Responses

In general, every time the RS485 master sends something to a slave (either with or without payload), the slave will answer (again either with or without payload) and the master has to answer again if the answer of the slave had a payload. After this whole process, the RS485 master increments the sequence number.

Modbus protocol overview

If something goes wrong in the whole process (e.g. CRC wrong, buffer full, packet length doesn't fit etc): The slave will stop responding and induce a timeout. In this case the RS485 master has to resend the request with the same sequence number.

If the RS485 master receives a response with wrong CRC or similar, he also has to resend the request with the same sequence number again.

Otherwise (everything went okay), the sequence number is incremented by the RS485 master. This approach ensures that there is never a request or response lost in the whole process.

Please note: If the RS485 master calls a function of a Brick or Bricklet in a RS485 slave stack, the response by the slave will likely not be the response to the function call. It will either be an empty message (ACK) or it will be a response to another function call from before or it will be a callback.

The approach should be that you poll every slave regularly (e.g. once per ms) with either an empty request if you have no data to transfer or with a request with payload if you have data to transfer. This will ensure that no messages pile up in the RS485 slave stack and you will get the responses to function calls and callbacks with a reasonable latency.

API

Links to the API reference for Bricks and Bricklets are listed in the following table. Further project descriptions can be found in the Kits section.

  API
Bricks  
DC API
ESP32 API
ESP32 Ethernet API
HAT API
HAT Zero API
IMU API
IMU 2.0 API
Master API
RED API
Servo API
Silent Stepper API
Stepper API
   
Bricklets  
Accelerometer API
Accelerometer 2.0 API
Air Quality API
Ambient Light API
Ambient Light 2.0 API
Ambient Light 3.0 API
Analog In API
Analog In 2.0 API
Analog In 3.0 API
Analog Out API
Analog Out 2.0 API
Analog Out 3.0 API
Barometer API
Barometer 2.0 API
CAN API
CAN 2.0 API
CO2 API
CO2 2.0 API
Color API
Color 2.0 API
Compass API
Current12 API
Current25 API
DC 2.0 API
Distance IR API
Distance IR 2.0 API
Distance US API
Distance US 2.0 API
DMX API
Dual Button API
Dual Button 2.0 API
Dual Relay API
Dust Detector API
E-Paper 296x128 API
Energy Monitor API
GPS API
GPS 2.0 API
GPS 3.0 API
Hall Effect API
Hall Effect 2.0 API
Humidity API
Humidity 2.0 API
IMU 3.0 API
Industrial Analog Out API
Industrial Analog Out 2.0 API
Industrial Counter API
Industrial Digital In 4 API
Industrial Digital In 4 2.0 API
Industrial Digital Out 4 API
Industrial Digital Out 4 2.0 API
Industrial Dual 0-20mA API
Industrial Dual 0-20mA 2.0 API
Industrial Dual AC In API
Industrial Dual AC Relay API
Industrial Dual Analog In API
Industrial Dual Analog In 2.0 API
Industrial Dual Relay API
Industrial PTC API
Industrial Quad Relay API
Industrial Quad Relay 2.0 API
IO-16 API
IO-16 2.0 API
IO-4 API
IO-4 2.0 API
Isolator API
Joystick API
Joystick 2.0 API
Laser Range Finder API
Laser Range Finder 2.0 API
LCD 128x64 API
LCD 16x2 API
LCD 20x4 API
LED Strip API
LED Strip 2.0 API
Line API
Linear Poti API
Linear Poti 2.0 API
Load Cell API
Load Cell 2.0 API
Moisture API
Motion Detector API
Motion Detector 2.0 API
Motorized Linear Poti API
Multi Touch API
Multi Touch 2.0 API
NFC API
NFC/RFID API
OLED 128x64 API
OLED 128x64 2.0 API
OLED 64x48 API
One Wire API
Outdoor Weather API
Particulate Matter API
Performance DC API
Piezo Buzzer API
Piezo Speaker API
Piezo Speaker 2.0 API
PTC API
PTC 2.0 API
Real-Time Clock API
Real-Time Clock 2.0 API
Remote Switch API
Remote Switch 2.0 API
RGB LED API
RGB LED 2.0 API
RGB LED Button API
RGB LED Matrix API
Rotary Encoder API
Rotary Encoder 2.0 API
Rotary Poti API
Rotary Poti 2.0 API
RS232 API
RS232 2.0 API
RS485 API
Segment Display 4x7 API
Segment Display 4x7 2.0 API
Servo 2.0 API
Silent Stepper 2.0 API
Solid State Relay API
Solid State Relay 2.0 API
Sound Intensity API
Sound Pressure Level API
Temperature API
Temperature 2.0 API
Temperature IR API
Temperature IR 2.0 API
Thermal Imaging API
Thermocouple API
Thermocouple 2.0 API
Tilt API
UV Light API
UV Light 2.0 API
Voltage API
Voltage/Current API
Voltage/Current 2.0 API
XMC1400 Breakout API