Modbus
Modbus is a communication protocol utilized in PLC networks. Originally developed for serial interfaces like RS232, RS422, and RS485, it was later expanded to include TCP mode. OIBus uses the jsmodbus library in TCP mode only.
Specific Settings
Connection Configuration
| Setting | Description | Example Value |
|---|---|---|
| Host | IP address or hostname of the Modbus server machine. | 192.168.1.100 |
| Port | Port to use for connection (502 by default). | 502 |
| Connection timeout | Maximum time to wait for a connection (in milliseconds). | 10000 |
| Retry interval | Time to wait (in milliseconds) between reconnections after a connection failure. | 5000 |
| Network timeout | Delay (in milliseconds) before TCP keepalive probes start being sent on an idle connection. Keeps the connection alive through firewalls and NAT devices that close idle sockets. | 15000 |
| Slave ID | Identifies the Modbus source machine (default is 1). | 1 |
| Address offset | For most PLCs, there is no offset (Modbus option). Some PLCs may start the address range at 1 instead of 0 (JBus option) | Modbus |
Data Format Options
| Setting | Description | Example Value |
|---|---|---|
| Endianness | Type of bit encoding. | Big Endian |
| Swap Bytes | Whether bytes within a 16-bit word should be swapped. | Enabled/Disabled |
| Swap Words | Whether 16-bit words should be swapped within a 32-bit group. | Enabled/Disabled |
Use the tester below to see how these three settings affect the decoded value for a given set of register values.
Presets
Query Optimisation
| Setting | Description | Example Value |
|---|---|---|
| Grouping gap | Maximum address gap (in registers) allowed when merging non-consecutive items of the same type into a single Modbus request. Set to 0 to batch only strictly consecutive addresses (default). | 0 – 100 |
OIBus always groups items of the same Modbus type (coil, discrete input, input register, holding register) whose addresses are consecutive into a single request, reducing round-trips to the device.
With a grouping gap > 0, items that are almost—but not quite—consecutive are also merged. For example, three holding registers at addresses 1, 3, and 5 would normally require three separate requests. With a grouping gap of 2, all three are read in one request (the two intermediate filler registers are fetched and discarded).
A larger gap trades a small amount of extra data on the wire (filler registers) for fewer TCP round-trips. This is usually beneficial when the device is slow to respond or when the network latency is high. Keep it at 0 if minimising traffic is more important than minimising round-trips.
Regardless of the grouping gap, OIBus never exceeds the Modbus specification limits per request:
- Coils / Discrete inputs (FC01 / FC02): 2 000 bits maximum.
- Input registers / Holding registers (FC03 / FC04): 125 words maximum.
Ranges that exceed these limits are automatically split into multiple requests.
Item Settings
| Setting | Description | Example Value |
|---|---|---|
| Address | Address of the register within the device, without the leading data type digit. Accepts a plain decimal number (e.g. 1) or a hexadecimal number prefixed with 0x (e.g. 0x0001). | 0x0001 |
| Modbus type | Specifies whether it's a coil, discrete input, input register, or holding register (default). | Holding Register |
| Data type | Relevant for holding registers or input registers. Defines the type of data fetched from the register (Bit, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float, Double). | UInt16 |
| Bit index | (Bit data type only) The index of the bit to retrieve from the read value (0 to 15). | 0 to 15 |
| Multiplier Coefficient | Multiplies the retrieved value (default is 1). | 1 |
PLC documentation typically uses the Modicon Convention Notation (MCN): a decimal number whose leading digit encodes the data type and whose remaining digits are the register number.
| Leading digit | Data type |
|---|---|
0 | Coil |
1 | Discrete Input |
3 | Input Register |
4 | Holding Register |
OIBus expects the address without the leading type digit, entered as a plain decimal number or as a hexadecimal number prefixed with 0x. The data type is declared separately via the Modbus type field.
Converting an MCN address to an OIBus address:
- Strip the leading type digit from the MCN address.
- Enter the remaining number directly. Both decimal and
0x-prefixed hexadecimal are accepted.
Examples:
| MCN address | Strip type digit | OIBus address | Modbus type |
|---|---|---|---|
40001 | 0001 | 1 or 0x0001 | Holding Register |
40100 | 0100 | 100 or 0x0064 | Holding Register |
30005 | 0005 | 5 or 0x0005 | Input Register |
00157 | 0157 | 157 or 0x009D | Coil |
MCN address ranges:
| Type | Standard (5 digits) | Extended (6 digits) |
|---|---|---|
| Coil | 00001 – 09999 | 000001 – 065535 |
| Discrete Input | 10001 – 19999 | 100001 – 165535 |
| Input Register | 30001 – 39999 | 300001 – 365535 |
| Holding Register | 40001 – 49999 | 400001 – 465535 |
Address offset: The Address offset setting controls whether register numbering starts at 0 (Modbus) or 1 (JBus). Most PLCs use the Modbus convention (no offset). Check your device documentation if values seem shifted by one.
For more details, see the Modicon Convention Notation (MCN).