This library allows your Arduino to communicate via Modbus protocol. 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 over IP).

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:

http://pt.wikipedia.org/wiki/Modbus http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b.pdf http://www.modbus.org/docs/Modbus_Messaging_Implementation_Guide_V1_0b.pdf

Author's note (motivation and thanks):

It all started when I found the Modbus RTU Arduino library of Juan Pablo Zometa. I had extend the library to support other Modbus functions.

After researching several other Modbus libraries I realized strengths and weaknesses in all of them. I also thought it would be cool have a base library for Modbus and derive it for each type of physical layer used.

I appreciate the work of all the authors of the other libraries, of which I used several ideas to compose the modbus-arduino. At the end of this document is a list of libraries and their authors.

• Operates as a slave (master mode in development)
• Supports Modbus Serial (RS-232 or RS485) and Modbus IP (TCP, not keep-alive)
• 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

Notes:

1. When using Modbus IP the transport protocol is TCP (port 502) and the connection is terminated to each transmitted message, that is, is not a keep-alive type connection.

2. The offsets for registers are 0-based. So be careful when setting your supervisory system or your testing software. For example, in ScadaBR (http://www.scadabr.com.br) offsets are 0-based, then, a register configured as 100 in the library is set to 100 in ScadaBR. On the other hand, in the CAS Modbus Scanner (http://www.chipkin.com/products/software/modbus-software/cas-modbus-scanner/) offsets are 1-based, so a register configured as 100 in library should be 101 in this software.

3. 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

There are four classes corresponding to four headers that may be used:

• Modbus - Base Library
• ModbusSerial - Modbus Serial Library (RS-232 and RS-485)
• ModbusIP - IP Modbus Library
• ModbusIP_ENC28J60 - IP Modbus Library (for ENC28J60 chip)

By opting for Modbus Serial or Modbus IP you must include in your sketch the corresponding header and the base library header, eg:

#include <Modbus.h>
#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:

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.

There are four examples that can be accessed from the Arduino interface, once you have installed the library. Let's look at the example Lamp.ino (only the parts concerning Modbus will be commented):

#include <Modbus.h>
#include <ModbusSerial.h>

Inclusion of the necessary libraries.

const int LAMP1_COIL = 100;

Sets the Modbus register to represent a lamp or LED. This value is the offset (0-based) to be placed in its supervisory or testing software. Note that if your software uses offsets 1-based the set value there should be 101, for this example.

ModbusSerial mb;

Create the mb instance (ModbusSerial) to be used.

mb.config (& Serial, 38400, SERIAL_8N1);
mb.setSlaveId (10);

Sets the serial port and the slave Id. Note that the serial port is passed as reference, which permits the use of other serial ports in other Arduino models. The bitrate and byte format (8N1) is being set. If you are using RS-485 the configuration of another pin to control transmission/reception is required. This is done as follows:

mb.config (& Serial, 38400, SERIAL_8N1, 2);

In this case, the pin 2 will be used to control TX/RX.

mb.addCoil (LAMP1_COIL);

Adds the register type Coil (digital output) that will be responsible for activating the LED or lamp and verify their status. The library allows you to set an initial value for the register:

mb.addCoil (LAMP1_COIL, true);

In this case the register is added and set to true. If you use the first form the default value is false.

mb.task ();

This method makes all magic, answering requests and changing the registers if necessary, it should be called only once, early in the loop.

digitalWrite (ledPin, mb.Coil (LAMP1_COIL));

Finally the value of LAMP1_COIL register is used to drive the lamp or LED.

In much the same way, the other examples show the use of other methods available in the library:

void addCoil (offset word, bool value)
void addHreg (offset word, word value)
void addIsts (offset word, bool value)
void addIreg (offset word, word value)

Adds registers and configures initial value if specified.

bool Coil (offset word, bool value)
bool Hreg (offset word, word value)
bool Ists (offset word, bool value)
bool IREG (offset word, word value)

Sets a value to the register.

bool Coil (offset word)
Hreg word (word offset)
bool Ists (offset word)
IREG word (word offset)

Returns the value of a register.

There are four examples that can be accessed from the Arduino interface, once you have installed the library. Let's look at the example Switch.ino (only the parts concerning Modbus will be commented):

#include <SPI.h>
#include <Ethernet.h>
#include <Modbus.h>
#include <ModbusIP.h>

Inclusion of the necessary libraries.

const int SWITCH_ISTS = 100;

Sets the Modbus register to represent the switch. This value is the offset (0-based) to be placed in its supervisory or testing software. Note that if your software uses offsets 1-based the set value there should be 101, for this example.

ModbusIP mb;

Create the mb instance (ModbusIP) to be used.

mac byte [] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
ip byte [] = {192, 168, 1, 120};
mb.config (mac, ip);

Sets the Ethernet shield. The values ​​of the MAC Address and the IP are passed by the config() method. The syntax is equal to Arduino Ethernet class, and supports the following formats:

void config (uint8_t * mac)
void config (uint8_t * mac, IPAddress ip)
void config (uint8_t * mac, IPAddress ip, IPAddress dns)
void config (uint8_t * mac, IPAddress ip, IPAddress dns, gateway IPAddress)
void config (uint8_t * mac, IPAddress ip, IPAddress dns, IPAddress gateway, subnet IPAddress)

Then we have:

mb.addIsts (SWITCH_ISTS);

Adds the register type Input Status (digital input) that is responsible for detecting if a switch is in state on or off. The library allows you to set an initial value for the register:

mb.addIsts (SWITCH_ISTS, true);

In this case the register is added and set to true. If you use the first form the default value is false.

mb.task ();

This method makes all magic, answering requests and changing the registers if necessary, it should be called only once, early in the loop.

mb.Ists (SWITCH_ISTS, digitalRead (switchPin));

Finally the value of SWITCH_ISTS register changes as the state of the selected digital input.

The Arduino standard Ethernet shield is based on chip WIZnet W5100, therefore the IDE comes with this library installed. If you have a shield based on ENC28J60 from Microchip you must install another Ethernet library. Among several available we chose EtherCard.

Download the EtherCard in https://github.com/jcw/ethercard and install it in your IDE. Use the following includes in your sketches:

#include <EtherCard.h>
#include <ModbusIP_ENC28J60.h>
#include <Modbus.h>

Done! The use of Modbus functions is identical to the ModbusIP library described above.

Notes:

1. EtherCard is configured to use the pins 10, 11, 12 and 13.

2. The voltage for shields based on ENC28J60 is generally 3.3V.

3. Another alternative is to use the ENC28J60 UIPEthernet library, available from https://github.com/ntruchsess/arduino_uip. This library was made so that mimics the same standard Ethernet library functions, whose work is done by Wiznet W5100 chip. As the ENC28J60 not have all the features of the other chip, the library UIPEthernet uses a lot of memory, as it has to do in software what in the shield Wiznet is made in hardware. If for some reason you need to use this library, just change the file ModbusIP.h and your sketches, changing the lines:

#include <Ethernet.h>

by

#include <UIPEthernet.h>

Then, you can use the ModbusIP library (not the ModbusIP_ENC28J60). In fact it allows any library or skecth, made for Wiznet shield be used in shield ENC28J60. The big problem with this approach (and why we chose EtherCard) is that UIPEthernet library + ModbusIP uses about 60% arduino program memory, whereas with Ethercard + ModbusIP_ENC28J60 this value drops to 30%!

Arduino Modbus RTU
Author: Juan Pablo Zometa, Samuel and Marco Andras Tucsni
Year: 2010
Website: https://sites.google.com/site/jpmzometa/

Simple Modbus
Author: Bester.J
Year: 2013 Website: https://code.google.com/p/simple-modbus/

Arduino-Modbus slave
Jason Vreeland [CodeRage]
Year: 2010
Website: http://code.google.com/p/arduino-modbus-slave/

Mudbus (Modbus TCP)
Author: Dee Wykoff
Year: 2011
Website: http://code.google.com/p/mudbus/

ModbusMaster Library for Arduino
Author: Doc Walker
Year: 2012
Website: https://github.com/4-20ma/ModbusMaster
Website: http://playground.arduino.cc/Code/ModbusMaster

http://github.com/andresarmento/modbus-arduino
prof (at) andresarmento (dot) com

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