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"
}

RTU request

{
  "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"
}

Maximal request

{
  "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"
}

Response examples

A response to a request is "0" when successful. A non-zero value response indicates an error occurred.

Successful response

{
    "result": {},
    "requestId": "00000007",
    "errorCode": 0,
    "errorMessage": ""
}

Error response

{
  "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

API referenceJSON Hub APIModbusconnectorModbus connectorModbus api reference

`"params"`

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.

Table 1. Modbus specific connector "params" property summaries

Property

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

1

integer

1 to 65535

dataCollectionIntervalMilliseconds

(optional) specifies the number of milliseconds to wait until reading PLC data again. For example, 15000 means 15 seconds

10000

integer

0 and negative values are invalid.

dataPersistenceStrategy

(optional) specifies when the connector writes collected data to the specified table

"onSchedule"

string

"onSchedule"

"onChange"

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

false

Boolean

true

false

serviceName

specifies which type of input to create

string

"modbus"

settings

specifies properties needed to configure the data source of the input

array of objects

settings

.modbusBaudRate

(optional) (RTU only) specifies the baud rate of the communication (9600, 19200, 57600, 115200, and so forth)

19200

int16

settings

.modbusDataAddressType

(optional) specifies if the settings.propertyMapList.modbusDataAddress is zero-based or one-based

"zeroBased"

string

"zeroBased"

"oneBased"

settings

.modbusDataBits

(optional) (RTU only) specifies the number of bits of data

8

int16

5, 6, 7, or 8

settings

.modbusParity

(optional) (RTU only) specifies the data parity

"even"

string

"none", "even", "odd"

settings

.modbusProtocol

specifies the protocol used to connect to the Modbus server

string

"TCP"

"RTU"

settings

.modbusSerialPort

(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

settings

.modbusServer

(TCP only) specifies the IP/hostname of the Modbus device

string

settings

.modbusServerPort

(TCP only) specifies the IP Port for the Modbus device for modbusTCP

int16

0 to 65535

settings

.modbusStopBits

(optional) (RTU only) specifies the bits of stop

1

int16

1 or 2

settings

.propertyMapList

specifies properties that represent the data being requested

array of objects

settings

.propertyMapList

.bitBooleanZeroValue

(optional) causes the connector to map a bit value of 1 to false and 0 to true when set to true. This property only applies when "modbusDataType" is set to "bitBoolean"

false

Boolean

true

false

settings

.propertyMapList

.bitEndPosition

(optional) identifies the end bit position from the data

value of the "bitStartPosition"

int16

0 to 15

settings

.propertyMapList

.bitEnumValues

(optional) specifies an array of JSON values, each typically a JSON string

Required if "modbusDataType" is "bitEnum"

array of strings

settings

.propertyMapList

.bitIntSigned

(optional) causes the connector to interpret the bits as a signed integer when set to true. This property only applies when the "modbusDataType" is set to "bitInt"

false

Boolean

true

false

settings

.propertyMapList

.bitLittleEndian

(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 true. This property only applies when the "modbusDataType" is set to "bitInt" or "bitEnum"

false

Boolean

true

false

settings

.propertyMapList

.bitReverseOrder

(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 true. Otherwise, the connector will start with the start bit position. This property only applies when the "modbusDataType" is set to "bitInt" or "bitEnum"

false

Boolean

true

false

settings

.propertyMapList

.bitStartPosition

identifies the start bit position from the data

Required if modbusDataType is , "bitString", "bitInt", or "bitEnum".

int16

0 to 15

settings

.propertyMapList

.bitStringOneValue

causes the connector to assign the value of "bitStringOneValue" to the JSON key defined by "propertyPath" when the bit value is 1

Required if "modbusDataType" is "bitString"

string

settings

.propertyMapList

.bitStringZeroValue

causes the connector to assign the value of "bitStringZeroValue" to the JSON key defined by "propertyPath" when the bit value is 0

Required if "modbusDataType" is "bitString"

string

settings

.propertyMapList

.modbusDataAccess

specifies the type of data structure to access

string

"coil"

"discreteinput"

"holdingregister"

"inputregister"

settings

.propertyMapList

.modbusDataAddress

specifies a particular data address. Set the "settings.modbusDataAddressType" to "oneBased" to make the address one-based instead of zero-based.

The "modbusDataAddress" property range is 0 to 65535 when "zeroBased" and 1 to 65536 when "oneBased"

int16

0 to 65536

settings

.propertyMapList

.modbusDataLen

specifies the number of 2-byte registers needed to hold the data — for example, if "modbusDataLen" is 2 the data is in 4 bytes (int32)

Note: if "modbusDataType" is specified, this value is ignored

Required if "modbusDataType" is not specified

integer

1, 2, or 4

settings

.propertyMapList

.modbusDataType

(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

"bitBoolean"

"bitEnum"

"bitInt"

"bitString"

"int8Signed"

"int8Unsigned"

"int16SignedAB"

"int16UnsignedAB"

"int16SignedBA"

"int16UnsignedBA"

"int32SignedABCD"

"int32UnsignedABCD"

"int32SignedDCBA"

"int32UnsignedDCBA"

"int32SignedBADC"

"int32UnsignedBADC"

"int32SignedCDAB"

"int32UnsignedCDAB"

"int64SignedABCDEFGH"

"int64UnsignedABCDEFGH"

"int64SignedBADCFEHG"

"int64UnsignedBADCFEHG"

"int64SignedCDABGHEF"

"int64UnsignedCDABGHEF"

"int64SignedDCBAHGFE"

"int64UnsignedDCBAHGFE"

"int64SignedHGFEDCBA"

"int64UnsignedHGFEDCBA"

"int64SignedGHEFCDAB"

"int64UnsignedGHEFCDAB"

"int64SignedFEHGBADC"

"int64UnsignedFEHGBADC"

"int64SignedEFGHABCD"

"int64UnsignedEFGHABCD"

"ieeeFloat32ABCD"

"ieeeFloat32CDAB"

"ieeeFloat32DCBA"

"ieeeFloat32BADC"

"ieeeFloat64ABCDEFGH"

"ieeeFloat64BADCFEHG"

"ieeeFloat64CDABGHEF"

"ieeeFloat64DCBAHGFE"

"ieeeFloat64HGFEDCBA"

"ieeeFloat64GHEFCDAB"

"ieeeFloat64FEHGBADC"

"ieeeFloat64EFGHABCD"

settings

.propertyMapList

.modbusUnitId

(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 1 to 255

Note: The original Modbus specification called this feature a slave address.

1

int16

0 to 255

settings

.propertyMapList

.propertyPath

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

JSON path

`"bitBooleanZeroValue"`

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.

`"bitEndPosition"`

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.

`"bitEnumValues"`

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

`"bitIntSigned"`

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.

`"bitLittleEndian"`

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.

`"bitReverseOrder"`

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.

`"bitStartPosition"`

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

`"bitStringOneValue"`

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.

`"bitStringZeroValue"`

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.

`"modbusDataAccess"`

Define the word size and its type (read-only or read-write).

Table 2. modbusDataAccess

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

`"modbusDataAddress"`

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.

`"modbusDataType"`

For more detailed information about the "modbusDataType" property, read our documentation on Modbus data types.

`"propertyPath"`

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