Concepts

Modbus concepts for FairCom Edge

Abstract

FairCom Edge has a Modbus service that allows FairCom Edge to connect to and interact with Modbus devices

FairCom Edge includes a Modbus service that allows FairCom Edge to connect to and interact with Modbus devices. Currently, the FairCom Edge server can capture Modbus data for forwarding to other systems.

The Modbus service is embedded within the FairCom jsonAction API. It can be enabled and disabled within the FairCom Edge server. You must enable the Modbus service before creating a Modbus input.

Modbus uses a client/server architecture. A hardware device acts as a Server and a FairCom Edge acts as a client.

Modbus protocol

The Modbus protocol is a data communications protocol created in 1979 for reading, writing, and controlling programmable logic controllers (PLCs), equipment, and sensors. It is a request-response protocol in which a client program sends a request packet to Modbus server software running on a device. A device responds with a response or exception packet.

Modbus works over serial and Ethernet transport protocols.

Modbus advantages

Modbus is simple, reliable, and fast. A device can process Modbus requests with little overhead. Modbus is best suited for quickly reading and writing up to 252 bytes of data per request. Modbus works well over serial communications because it limits the payload size.

Modbus disadvantages

The data in a Modbus request and response is limited to 252 bytes. it can only reference up to 65,536 data items in a single device unit, but a device may support multiple units. Modbus only supports 2-byte values and single-bit on/off Boolean values. FairCom's Modbus driver can convert two=byte values to unsigned integers from 0 to 65537, signed integers from -32768 to 32767, and floating-point values.

Use a different protocol when you need to read and write a larger quantity and variety of data types or want a single response to include more than 252 bytes of data.

Protocol Data Unit (PDU)

The Modbus protocol defines three types of packets sent to and from devices: request, responses, and exceptions. A Modbus packet sent between a client and a server is called a Protocol Data Unit (PDU). The payload of a PDU is limited to 253 bytes, One byte is a function code, and 252 bytes are data.

A request PDU consists of a one-byte function code followed by up to 252 bytes of request parameters.
A response PDU consists of a one-byte function code followed by up to 252 bytes of response data. A function code from 1 to 127 specifies a successful response, and a function code from 128 to 255 specifies an exception response.
An exception PDU consists of a one=byte function code 0x80 followed by a one-byte exception code.

The parameters in a request and response vary by function code. Parameters typically include a data reference, variable counts, and variable values. Data references and values are big-endian encoded.

Function code

A function code is a single-byte integer.

A request function code is a one-byte integer from 1 to 127. It identifies the action that a device should perform. Some request functions have sub-function codes that require the device to perform a more specific action.
A response function code is a one-byte integer from 1 to 255. When a response is successful, it contains the same function code as the request. When a response communicates a failure, the function code is the request function code plus 128. Thus, response function codes range from 128 to 255.

Data reference or address

A data reference is an unsigned 16-bit integer. Thus, the Modbus protocol can only address up to 65,536 data items in a device. A data reference uniquely identifies each data item Modbus can read and write on a device. A device maps each data reference to a read-only or read-write data type that is either a Boolean value or a 16-bit integer. Modbus allows a device to map any data reference to any of its supported types.

A data reference is not a memory address. It is a logical reference to a data value. A device may map any data reference to any internal memory address. For example, a device may define data reference 1 as a 16-bit read-only input register and data reference 2 as a 1-bit read-write coil. This example shows that data references are not contiguous memory addresses because a 16-bit read-only value at data reference 1 would overlap with a 1-bit read-write value at data reference 2.

Use the "modbusDataAddress" property in the FairCom Modbus Connector to set a data reference.

Note

Vendor documentation often refers to a data reference using PDU Address, Register Number, and Address Code. The FairCom Modbus Connector uses the term "modbusDataAddress". It defaults to one-based and allows you to choose whether the address is one-based or zero-based using the property "modbusAddressType".

Important

In the binary PDU, a data reference has a value from 0 to 65,535, but Modbus requires documentation software to use a one-based data reference with a value from 1 to 65,536. Software that communicates using Modbus takes a one-based data reference number and converts it to zero-based before putting it in a PDU. Similarly, Modbus requires all its identifiers to be one-based in the documentation but zero-based in the PDU.

Data types

Modbus defines four data types, which are either 1-bit Boolean values or 16-bit words combined with read-only or read-write abilities.

Table 1. Data types

Data Type	Read-write Capabilities	Bit Size
Discrete Input	read-only	single bit
Coil	read-write	single bit
Input Register	read-only	16 bits
Holding Register	read-write	16 bits

Function codes

Most Modbus functions read or write data types at a specific data reference or across a range of data references. The Modbus specification defines the behavior of function codes 1 through 65 and 111 through 127. A device can define the behavior of the remaining function codes.

FairCom Edge automatically uses the correct function code to read data. Contact FairCom to request enhancements to FairCom's Modbus Connector to support additional functionality.

Table 2. Function codes

Function Code	Sub Code	Category	Title	Description
1		Read Data	Read Coils as Booleans	This code requests a device to read 1 to 2000 contiguous data references as coils, a series of 1-bit, read-write Boolean values. The request supplies a starting data reference and an integer quantity. The response contains a series of one-bit values packed into the bytes of the response PDU. A bit value of 1 is ON or `true`, and 0 is OFF or `false`. The device responds with success or an exception code of 1, 2, 3, or 4.
2		Read Data	Read Discrete Inputs as Booleans	This code requests a device to read 1 to 2000 contiguous data references as discrete inputs, a series of 1-bit, read-only Boolean values. The request supplies a starting data reference and an integer quantity. The response contains a series of one-bit values packed into the bytes of the response PDU. A bit value of 1 is ON or `true`, and 0 is OFF or `false`. The device responds with success or an exception code of 1, 2, 3, or 4.
3		Read Data	Read Holding Registers as Integers	This code requests a device to read 1 to 125 contiguous data references as holding registers, a series of 16-bit read-write integers. The request supplies a starting data reference and an integer quantity. The response contains a series of 16-bit integers. The device responds with success or an exception code of 1, 2, 3, or 4.
4		Read Data	Read Input Registers as Integers	This code requests a device to read 1 to 125 contiguous data references as holding registers, a series of 16-bit read-only integers. The request supplies a starting data reference and an integer quantity. The response contains a series of 16-bit integers. The device responds with success or an exception code of 1, 2, 3, or 4.
5		Write Data	Write a Boolean to a Coil	This code requests a device to write one `true` or `false` Boolean value to a data reference as a coil. A coil is a 1-bit read-write value. The request supplies a data reference and `true` or `false`. When the Modbus driver creates the PDU, it converts a value of `true` to `0xFFFF` and `false` to `0x0000`. The device responds with success or an exception code of 1, 2, 3, or 4.
6		Write Data	Write an Integer to a Holding Register	This code requests a device to write one integer value to a data reference as a holding register. A holding register is a 16-bit read-write integer value. The request supplies a data reference and a two-byte integer number between 0 and 65535. The device responds with success or an exception code of 1, 2, 3, or 4.
7		Serial Info	Read Serial Exception Status	This function applies only to serial communications. A device responds with the status of the eight serial exception status outputs packed into one byte as 8 bits.
8	0-18, 29	Serial Info	Diagnose Serial Communications	This function applies only to serial communications. Supply a two-byte sub-function code to specify which serial communication test you want the device to run.
11		Serial Info	Get Serial Comm Event Counter	This function applies only to serial communications. A device returns its serial status and event count.
12		Serial Info	Get Serial Comm Event Log	This function applies only to serial communications. A device returns its serial status, event count, and event bytes.
15		Write Data	Write Booleans to Coils	This code requests a device to write multiple `true` or `false` Boolean values to a continuous range of data references as a series of coils. A coil is a 1-bit read-write value. The request supplies a starting data reference and multiple `true` or `false` values. When the Modbus driver creates the PDU, it converts each `true` to `0xFFFF` and `false` to `0x0000`. The device responds with success or an exception code of 1, 2, 3, or 4.
16		Write Data	Write Integers to Holding Registers	This code requests a device to write multiple integer values to a continuous range of data references. A holding register is a 16-bit read-write integer value. The request supplies a starting data reference and multiple integer values. The device responds with success or and exception code of 1, 2, 3, or 4.
17		Read Device Info	Report Server ID	This function applies only to serial communications. A device returns its server ID and current run status (on or off).
20		Read Data	Read 2-byte records from files	This code requests a device to read multiple ranges of 2-byte records from one or more files. The request supplies a series of record-read requests. Each record-read request consists of a file number, starting record number, and record count. Each file has a unique identifier from 1 to 65,536. Each record in a file has a unique identifier between 1 and 10,000. The device responds with the requested record data. This feature has limited usability because the data in the response can be at most 252 bytes. The device responds with success or an exception code of 1, 2, 3, or 4.
21		Write Data	Write 2-byte records to files	This code requests a device to write multiple ranges of 2-byte records to one of more files. The request supplies a series of record write requests. Each record write request consists of a file number, starting record number, record count, and record data. Each file has a unique identifier from 1 to 65,536. Each record in a file has a unique identifier between 1 an d10,000. This feature has limited usability because the data in the request can be at most 252 bytes. Each record write request has an overhead of 7 bytes, followed by the data. The device responds with success or an exception code of 1, 2, 3, or 4.
22		Write Data	Mask a Holding Register	This code requests a device to mask a holding register. The request contains the holding register's data reference, an AND mask, and an OR mask. If the OR mask is zero, the device ANDs the current contents with the AND mask. If the AND mask is zero, the device sets the holding register to the OR mask. If both the AND and OR masks are not zero, the device uses the following formula: Holding Register Value = (Current Contents AND And_Mask) OR (Or_Mask AND (NOT And_Mask)).
23		Read & Write Data	Read and Write Holding Registers	This code requests a device to write multiple integer values to a continuous range of data references. It also specifies a continuous range of data references to read. A holding register is a 16-bit read-write integer value. The request supplies a starting read reference and a read count value. The request supplies a starting read reference and a read count followed by a starting write reference, a write count, and multiple integer values to write. The device responds with success or an exception code of 1, 2, 3, or 4. When successful, it returns the values of the read registers.
24		Read Data	Read FIFO Queue of Registers	This code requests a device read integer values from a First-In-First-Out (FIFO) queue. The function reads the queue items without removing them. The request supplies the queue's data reference. The response includes the current queue count and the requested queue data. If the Queue count exceeds 31, the device responds with an exception of 3 (Illegal Data Value).
43	13		CANopen Services	This code encapsulates the CANopen protocol inside a Modbus PDU.
43	14	Read Device Info	Device Identification	This code encapsulates a device identification protocol inside a Modbus PDU and returns the device information (if supported). The request contains a Type ID from 1 to 4 and an Object ID from 1 to 255. The response contains the requested device information as ASCII strings. Modbus encapsulates this function because it returns ASCII strings, and Modbus only supports single-bit Boolean values and 16-bit integer numbers. When the `Type ID is 1`, the Object ID must be 0. The response returns 3 ASCII strings: 1) Vendor Name, 2) Product Code, and 3) Major/Minor Revision. When the `Type ID is 2`, the Object ID must be 4, 5, 6, or 7. The response returns an ASCII string for one of the following values: 4) Vendor URL, 5) Product Name, 6) Model Name, or 7) User/Application Name. When the `Type ID is 3`, the Object ID must be a value from 128 through 256. The device defines the data types of these values. The response returns the value of the requested object. When the `Type ID is 4`, the Object ID can be a value from 1 through 256. The response returns the value of the requested object.

Exception codes

When a response function code is an exception number between 128 and 255, the response also contains a one-byte exception code that helps identify the cause of the problem. The following table describes each exception code.

Table 3. Exception codes

Code	Name	Description
1	ILLEGAL FUNCTION	The function code in the request is not allowed by the device. Either the function is unsupported, or the device is in the wrong state to allow it. For example, a device may not support function code 2, or the device may require you to configure it to support Modbus.
2	ILLEGAL DATA ADDRESS	A device does not support the requested data reference. For example, a device may only support data references from 1 to 100, but a request specifies a data reference of 2001. A device does not support the range of requested data. For example, a device may only support data references from 1 to 100, but a request specifies a starting data reference of 99 and a quantity of 5.
3	ILLEGAL DATA VALUE	A request contains a value that a device does not allow. For example, the length is incorrect. It may mean that a device does not support the function code for the requested data reference. For example, a device may specify that data reference 100 is a discrete input, but the request uses function 3, which requires the data to be a holding register. A device should not return this error when a function writes a value to a data reference that does not match the device's expectation. For example, a device may only be able to process values 1 or 2 at a data reference, but a function writes the value 3 to the data reference. The device should not return error 3; instead, it should write the value or ignore the write request.
4	SERVER DEVICE FAILURE	A device encountered an unrecoverable error while attempting to process the requested function.
5	ACKNOWLEDGE	A device returns this code when processing a function requires a long time. It helps prevent a timeout. Client software can issue a Poll Program Complete request to determine if the device has completed the request.
6	SERVER DEVICE BUSY	A device returns this code when it is too busy to process the request. Client software can later retransmit the request.
8	MEMORY PARITY ERROR	A device returns this code when it has a memory error in processing function codes 20 and 21. Client software can later retransmit the request.
10	GATEWAY PATH UNAVAILABLE	A gateway returns this code when it does not know how to communicate with a device. it may mean the gateway is misconfigured or overloaded.
11	GATEWAY TARGET DEVICE FAILED TO RESPOND	A gateway returns this code when it fails to communicate with a device. It typically means the device failed to respond. The device may have a network issue or be offline.

Sub-function codes

The Modbus specification defines the following sub-function codes. The remaining codes between 0 and 65535 are reserved. The specification provides a detailed explanation of each one.

Table 4. Sub-function codes

Sub-function	Title	Description
0	Return Query Data	This code requests a device to echo request to the sender.
1	Restart Communications Option	This code requests a device to restart the communication system.
2	Return Diagnostic Register	This code requests a device to return its 16-bit serial diagnostic register.
3	Change ASCII Input Delimiter	This code requests a device to change its ASCII input delimiter to the last byte in the PDU.
4	Force Listen Only Mode	This code requests a device to listen but not respond to requests. It prevents the device from processing Modbus requests. Use it to remove a malfunctioning device from the communication system.
10	Clear Counters and Diagnostic Register	This code requests a device to clear its serial counters and diagnostics register.
11	Return Bus Message Count	This code requests a device to return the count of messages detected (but not necessarily processed) since its last restart or reset.
12	Return Bus Communication Error Count	This code requests that a device return the number of CRC errors it has received since its last restart or reset.
13	Return Bus Exception Error Count	This code requests a device to return the count of Modbus exception responses it has returned since its last restart or reset.
14	Return Server Message Count	This code requests a device to return the count of messages it has processed since its last restart or reset.
15	Return Server No Response Count	This code requests a device to return the count of messages for which it has not returned a response since its last restart or reset.
16	Return Server NAK Count	This code requests a device to return the count of Negative Acknowledge (NAK) exception responses since its last restart or reset.
17	Return Server Busy Count	This code requests a device to return the count of Server Device Busy exception responses since its last restart or reset.
18	Return Bus Character Overrun Count	This code requests a device to return the count of character overrun conditions since its last restart or reset.
20	Clear Overrun Counter and Flag	This code requests a device to clear the character overrun counter and flag.