/modbus-arduino

A library that allows your Arduino to communicate via Modbus protocol, acting as a slave. Application layer library (OSI 7), used by all implementations over serial line and TCP/IP.

Primary LanguageC++BSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

Modbus Library for Arduino

Allows your Arduino to communicate via Modbus protocol

GitHub release (latest by date including pre-releases) PlatformIO Registry Arduino Registry

Framework Platform ATMELAVR Platform ATMELSAM Platform Teensy Platform ESP8266 Platform ESP32

Modbus Logo

The Modbus is a master-slave protocol used in industrial automation and can be used in other areas, such as home automation.

The Modbus generally uses serial RS-232 or RS-485 as physical layer (then called Modbus Serial) and TCP/IP via Ethernet or WiFi (Modbus TCP). But it is also possible to associate the Modbus application protocol on any other physical layer, such as the radio for example (with MobdusRadio for example).

Modbus Stack

In the current version the library allows the Arduino operate as a slave, supporting Modbus Serial and Modbus over IP. For more information about Modbus see:

Features

  • Operates as a slave (master mode in development)
  • Supports Modbus over Serial line (RS-232 or RS485) and Modbus TCP
  • Reply exception messages for all supported functions
  • Modbus functions supported:
    • 0x01 - Read Coils
    • 0x02 - Read Input Status (Read Discrete Inputs)
    • 0x03 - Read Holding Registers
    • 0x04 - Read Input Registers
    • 0x05 - Write Single Coil
    • 0x06 - Write Single Register
    • 0x0F - Write Multiple Coils
    • 0x10 - Write Multiple Registers
    • 0x11 - Report Server ID

A set of examples is available for each of the Modbus-derived classes, for example:

  • Lamp: Use a coil to turn on and off a LED (0x05 and 0x01 functions)
  • LampDimmer: Use a holding register to control the brightness of a LED (0x06 and 0x03 functions)
  • Switch: Use a discrete input to read the state of a switch (0x02 function)
  • TempSensor: Use a input register to read the temperature from a sensor (0x04 function)
  • Servo: Use a holding register to control the position of a servo motor (0x06 an 0x03 function). Show how to define boundaries for the register.
  • LampEncrypted: Use a coil to turn on and off a LED (0x05 and 0x01 functions) with encrypted communication.

All examples show the use of 0x11 function to report the slave ID.

Notes:

  1. The offsets for registers are 0-based. So be careful when setting your supervisory system or your testing software. If offsets are 1-based, so a register configured as 100 in library should be 101 in this software.

  2. Early in the library Modbus.h file there is an option to limit the operation to the functions of Holding Registers, saving space in the program memory. Just comment out the following line:

     #define USE_HOLDING_REGISTERS_ONLY

Thus, only the following functions are supported:

  • 0x03 - Read Holding Registers
  • 0x06 - Write Single Register
  • 0x10 - Write Multiple Registers

You may test the library using the MbPoll software. For example, to turn on the led in the Lamp example, just do:

$ mbpoll -m rtu -b38400 -a10 -t0   /dev/tnt1 1
  mbpoll 1.5-2 - ModBus(R) Master Simulator
  Copyright (c) 2015-2023 Pascal JEAN, https://github.com/epsilonrt/mbpoll
  This program comes with ABSOLUTELY NO WARRANTY.
  This is free software, and you are welcome to redistribute it
  under certain conditions; type 'mbpoll -w' for details.

  Protocol configuration: ModBus RTU
  Slave configuration...: address = [10]
                          start reference = 1, count = 1
  Communication.........: /dev/tnt1,      38400-8E1
                          t/o 1.00 s, poll rate 1000 ms
  Data type.............: discrete output (coil)

  Written 1 references.

How to

There are five classes corresponding to six headers that may be used:

By opting for Modbus Serial, TCP or Radio you must include in your sketch the corresponding header :

#include <ModbusSerial.h>

Modbus Jargon

In this library was decided to use the terms used in Modbus to the methods names, then is important clarify the names of register types:

Register type Use as Access Library methods
Coil Digital Output Read/Write addCoil(), coil(), setCoil()
Holding Register Analog Output Read/Write addHreg(), hreg(), setHreg()
Input Status Digital Input Read Only addIsts(), ists(), setIsts()
Input Register Analog Input Read Only addIreg(), ireg(), setIreg()

Notes:

  1. Input Status is sometimes called Discrete Input.
  2. Holding Register or just Register is also used to store values in the slave.
  3. Examples of use: A Coil can be used to drive a lamp or LED. A Holding Register to store a counter or drive a Servo Motor. A Input Status can be used with a reed switch in a door sensor and a Input Register with a temperature sensor.

License

The code in this repo is licensed under the BSD New License. See LICENSE for more info.