Modbus API reference
Modbus connector programming specifications for FairCom Edge
FairCom provides special API actions for Modbus TCP connectors and transforms. The Modbus TCP service must be enabled in order to complete FairCom Modbus API actions.
Request examples
Note
The FairCom createInput JSON action is used to define the specifics of a connector device and the desired data.
Minimal request
{
"api": "hub",
"action": "createInput",
"params": {
"inputName": "modbusTCP",
"serviceName": "modbus",
"settings": {
"modbusProtocol": "TCP",
"modbusServer": "127.0.0.1",
"modbusServerPort": 1505,
"propertyMapList": [
{
"propertyPath": "temperature",
"modbusDataAccess": "holdingregister",
"modbusDataAddress": 1199,
"modbusUnitId": 5,
"modbusDataLen": 1
}
]
},
"tableName": "modbusTableTCP"
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
{
"api": "hub",
"action": "createInput",
"params": {
"inputName": "modbusRTU",
"serviceName": "modbus",
"settings": {
"modbusProtocol": "RTU",
"modbusSerialPort": "COM2",
"modbusBaudRate": 19200,
"modbusParity": "None",
"modbusDataBits": 8,
"modbusStopBits": 2,
"modbusDataCollectionIntervalMilliseconds": 5000,
"propertyMapList": [
{
"propertyPath": "temperature",
"modbusDataAccess": "holdingregister",
"modbusDataAddress": 1199,
"modbusUnitId": 5,
"modbusDataLen": 1
}
]
},
"tableName": "modbusTableRTU"
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
{
"api": "hub",
"action": "createInput",
"params": {
"inputName": "modbusTCP",
"serviceName": "modbus",
"settings": {
"modbusProtocol": "TCP",
"modbusServer": "127.0.0.1",
"modbusServerPort": 1505,
"modbusDataAddressType": "zeroBased",
"modbusDataCollectionIntervalMilliseconds": 5000,
"propertyMapList": [
{
"propertyPath": "temperature",
"modbusDataAddress": 1199,
"modbusDataAccess": "holdingregister",
"modbusUnitId": 5,
"modbusDataLen": 1,
"modbusDataType": "int16SignedAB"
},
{
"propertyPath": "volume",
"modbusDataAddress": 1299,
"modbusDataAccess": "holdingregister",
"modbusUnitId": 5,
"modbusDataLen": 2,
"modbusDataType": "ieeeFloat32ABCD"
},
{
"propertyPath": "status",
"modbusDataAddress": 1199,
"modbusDataAccess": "coil",
"modbusUnitId": 5,
"modbusDataLen": 1,
"modbusDataType": "int8Signed"
}
]
},
"ownerName": "admin",
"tableName": "modbusTableTCP",
"retentionPolicy": "autoPurge",
"retentionPeriod": 30,
"retentionUnit": "day",
"metadata": {}
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
A response to a request is "0" when successful. A non-zero value response indicates an error occurred.
{
"result": {},
"requestId": "00000007",
"errorCode": 0,
"errorMessage": ""
}
{
"result": {},
"requestId": "00000011",
"debugInfo": {
"request": {
"api": "hub",
"action": "createInput",
"params": {
"inputName": "modbusTCP",
"serviceName": "modbus",
"settings": {
"modbusProtocol": "TCP",
"modbusServer": "127.0.0.1",
"modbusServerPort": 1505,
"propertyMapList": [
{
"propertyPath": "temperature",
"modbusDataAddress": "holdingregister",
"modbusDataAddress": 1199,
"modbusUnitId": 5,
"modbusDataLen": 1
}
]
},
"tableName": "modbusTableTCP"
},
"requestId": "00000011",
"debug": "max",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
},
"errorCode": 12012,
"errorMessage": "There is already an integration with name of [modbusTCP].",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Modbus connector programming specifications for FairCom Edge
The "params"
property is an object that contains an action's parameters. Each action defines its own required and optional properties.
Note
See createInput for "params"
properties that are common to all connectors.
"params"
property summariesProperty | Description | Default | Type | Limits | |||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
dataCollectionBufferCount | (optional) specifies the number of times the collector retrieves and caches data from the device before writing the data to the integration table |
| integer |
| |||||||||||||||||||||||||||||||||||||||||||||||||
dataCollectionIntervalMilliseconds | (optional) specifies the number of milliseconds to wait until reading PLC data again. For example, |
| integer |
| |||||||||||||||||||||||||||||||||||||||||||||||||
dataPersistenceStrategy | (optional) specifies when the connector writes collected data to the specified table |
| string |
| |||||||||||||||||||||||||||||||||||||||||||||||||
immediatelyCollectDataOnStart | (optional) configures the input to collect data immediately when the server or connector starts. The occurs even if the data persistence strategy is to collect data changes |
| Boolean |
| |||||||||||||||||||||||||||||||||||||||||||||||||
serviceName | specifies which type of input to create |
| string |
| |||||||||||||||||||||||||||||||||||||||||||||||||
settings | specifies properties needed to configure the data source of the input |
| array of objects | ||||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) (RTU only) specifies the baud rate of the communication ( |
| int16 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) specifies if the settings.propertyMapList.modbusDataAddress is zero-based or one-based |
| string |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) (RTU only) specifies the number of bits of data |
| int16 |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) (RTU only) specifies the data parity |
| string |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| specifies the protocol used to connect to the Modbus server |
| string |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (RTU only) specifies the name of the serial port handled by the OS (such as "/dev/ttyS0" or "/dev/ttyUSB0"). On Windows, it is necessary to prepend the COM name with "\\.\" if the COM number is greater than 9. For example, "\\\\.\\COM10". For Windows naming conventions, see Naming Files, Paths, and Namespaces . |
| string | ||||||||||||||||||||||||||||||||||||||||||||||||||
| (TCP only) specifies the IP/hostname of the Modbus device |
| string | ||||||||||||||||||||||||||||||||||||||||||||||||||
| (TCP only) specifies the IP Port for the Modbus device for modbusTCP |
| int16 |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) (RTU only) specifies the bits of stop |
| int16 |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| specifies properties that represent the data being requested |
| array of objects | ||||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) causes the connector to map a bit value of |
| Boolean |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) identifies the end bit position from the data | value of the | int16 |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) specifies an array of JSON values, each typically a JSON string | Required if | array of strings | ||||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) causes the connector to interpret the bits as a signed integer when set to |
| Boolean |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) causes the connector to interpret a range of nine or more bits in little-endian order instead of big-endian order when set to |
| Boolean |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) causes the connector to assign bit values to the integer value starting from the end bit position to the start bit position when set to |
| Boolean |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| identifies the start bit position from the data | Required if modbusDataType is , | int16 |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| causes the connector to assign the value of | Required if | string | ||||||||||||||||||||||||||||||||||||||||||||||||||
| causes the connector to assign the value of | Required if | string | ||||||||||||||||||||||||||||||||||||||||||||||||||
| specifies the type of data structure to access |
| string |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| specifies a particular data address. Set the The |
| int16 |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| specifies the number of 2-byte registers needed to hold the data — for example, if Note: if | Required if | integer |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) specifies how to convert Modbus binary data types to JSON types. Choose a type that matches the byte order of the data type. The byte order is specified using the letters ABCDEFGH |
| string |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| (optional) specifies a device unit number that uniquely identifies a device. Modbus communicates to a device or gateway on one IP address and port. A device or gateway may proxy Modbus communications across multiple Modbus devices. The unit number uniquely identifies each of these devices. This property also applies to serial communications. For serial communication, the range is Note: The original Modbus specification called this feature a slave address. |
| int16 |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| specifies the JSON path in the JSON document where the connector puts the data it collects. It is the tag name of the data being collected |
| string |
The "bitBooleanZeroValue"
property is optional and defaults to false
. It applies when the "modbusDataType"
property is set to "bitBoolean"
. When set to true
, the connector maps a bit value of 1
to false
and 0
to true
.
The "bitEndPosition"
property is a zero-based bit position with a value from 0
to 15
. It is required only when the "modbusDataType"
property is set to "bitInt"
or "bitEnum"
. When present, it must be greater than or equal to "modbusStartBitPosition"
. When omitted, it defaults to the value of the "bitStartPosition"
property.
The "bitEnumValues"
property is an array of JSON values, each typically a JSON string. It is required only when the "modbusDataType"
property is set to "bitEnum"
.
The "bitIntSigned"
property is optional and defaults to false
. It applies when the "modbusDataType"
property is set to "bitInt"
. When set to true
, the connector interprets the bits as a signed integer.
The "bitLittleEndian"
property is optional and defaults to false
. It applies when the "modbusDataType"
property is set to "bitInt"
or "bitEnum"
. When set to true
, the connector interprets a range of nine or more bits in little-endian order instead of big-endian order. A range of eight bits or less is unaffected by endian status. The Modbus "int16SignedBA"
or "int16UnsignedBA"
data types are in little-endian order.
The "bitReverseOrder"
property is an optional Boolean value. It applies when the "modbusDataType"
property is set to "bitInt"
or "bitEnum"
. When true
, the connector assigns bit values to the integer value starting from the end bit position to the start bit position; otherwise, it starts with the start bit position. It places bit values into the integer, starting from the rightmost bit to the leftmost.
For example, if "bitReverseOrder"
is false
, "bitStartPosition"
is 5
, and "bitEndPosition"
is 6
, the connector works its way from the end position to the starting position, setting bits in the integer from right to left. For example, it takes the bit value at the bit end position and sets it into the rightmost bit in the integer. It then takes the bit value at the next-to-last position and sets it to the left of the previous bit. Thus, if 1
is the bit value in the Modbus register at bit position 5
and 0
is the value of bit position 6
, the resulting binary integer value is 0000 0010
. Given the same bit values, if "bitReverseOrder"
is true
, the resulting integer value is 0000 0001
.
The "bitStartPosition"
property is a zero-based bit position with a value from 0
to 15
. It is required when the "modbusDataType"
property is set to "bitBoolean"
, "bitString"
, "bitInt"
, or "bitEnum"
.
The "bitStringOneValue"
property is a string and is required when the "modbusDataType"
property is set to "bitString"
. When the bit value is 1
, the connector assigns the value of "bitStringOneValue"
to the JSON key defined by "propertyPath"
. You may set it to any string value, including the empty string ""
, "null"
, "true"
, "false"
, "2"
, or "-9"
. You cannot set it to a non-string value, such as the JSON symbols null
, true
, false
, or a number like 2
, or -9
.
The "bitStringZeroValue"
property is a string and is required when the "modbusDataType"
property is set to "bitString"
. When the bit value is 0
, the connector assigns the value of "bitStringZeroValue"
to the JSON key defined by "propertyPath"
. You may set it to any string value, including the empty string ""
, "null"
, "true"
, "false"
, "2"
, or "-9"
. You cannot set it to a non-string value, such as the JSON symbols null
, true
, false
, or a number like 2
, or -9
.
Define the word size and its type (read-only or read-write).
Data Access | Size | Type |
---|---|---|
holdingregister | 2 byte word | Read-write |
coil | 1 bit | Read-write |
inputregister | 2 byte word | Read-only |
discreteinput | 1 bit | Read-only |
The "modbusDataAddress"
property specifies where the Modbus protocol should read or write a value to a memory address on a device. By default it is zero-based and ranges from 0 to 65,535.
Some vendors document data addresses as one-based values. Set the "modbusDataAddressType"
to "oneBased"
to configure the "modbusDataAddress"
property to use a one-based address, which ranges from 1 to 65,536.
For more detailed information about the "modbusDataType"
property, read our documentation on Modbus data types.
The "propertyPath"
property is a required string that specifies the JSON Path in the JSON document where the connector puts the data it collects. It is the tag name of the data being collected. You can use this property to take collected data and store it in any location in the JSON document generated by the connector. For example, the setting "propertyPath": "temperature"
causes the server to take a value it collects, such as 20.1
, and store it in a "temperature"
property, such as { "temperature": 20.1 }
.