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

{
  "authToken": "<yourAuthTokenHere>",
  "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"
  }
}

RTU request

{
  "authToken": "<yourAuthTokenHere>",
  "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"
  }
}

Maximal request

{
  "authToken": "' + token + '", 
  "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": {}
  }
}

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

{
  "authToken": "validToken",
  "result": {},
  "requestId": "00000011",
  "debugInfo": {
    "request": {
      "authToken": "validToken",
      "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"
    }
  },
  "errorCode": 12012,
  "errorMessage": "There is already an integration with name of [modbusTCP]."
}

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" properties summary

Property

Description

Default

Type

Limits

serviceName

specifies which type of input to create

Required - No default value

string

"modbus"

settings

specifies properties needed to configure the data source of the input

Required - No default value

array of objects

settings

.modbusBaudRate

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

19200

int16

settings

.modbusDataAddressType

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

"zeroBased"

string

"zeroBased"

"oneBased"

settings

.modbusDataBits

(RTU only) specifies the number of bits of data

8

int16

5, 6, 7, or 8

settings

.modbusDataCollectionIntervalMilliseconds

specifies how often the data should be requested in milliseconds

10000

int32

0 to 2147483647

settings

.modbusGroupedDataPoints

specifies the number of times the collector retrieves and caches data from the device before writing the data to the integration table.

This option combines multiple data collection events and inserts them into the integration table as one MQTT message.

If this value is more than 1, the connector converts each set of collected data into a JSON object and adds the object to an array inside a JSON document. When the count is reached, the connector writes the JSON document to the source_payload field of a record it inserts into the integration table.

1

int16

1 to 65535

settings

.modbusParity

(RTU only) specifies the data parity

"even"

string

"none", "even", "odd"

settings

.modbusProtocol

specifies the protocol used to connect to the Modbus server

Required - No default value

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 .

Required - No default value

string

settings

.modbusServer

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

Required - No default value

string

settings

.modbusServerPort

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

Required - No default value

int16

0 to 65535

settings

.modbusStopBits

(RTU only) specifies the bits of stop

1

int16

1 or 2

settings

.propertyMapList

specifies properties that represent the data being requested

Required - No default value

array of objects

settings

.propertyMapList

.propertyPath

specifies the JSON property that this data will be identified by

Required - No default value

string

settings

.propertyMapList

.modbusDataAccess

specifies the type of data structure to access

Required - No default value

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

Required - No default value

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 - No default value

integer

1, 2, or 4

settings

.propertyMapList

.modbusDataType

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.

Optional

string

"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

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

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.