API reference

Modbus connector programming specifications for FairCom Edge

Abstract

FairCom provides special API actions for Modbus TCP connectors and transforms

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.

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,
          "modbusSlave": 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,
          "modbusSlave": 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,
      "modbusDataCollectionIntervalMilliseconds": 5000,
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "modbusDataAddress": 1199,
          "modbusDataAccess": "holdingregister",
          "modbusSlave": 5,
          "modbusDataLen": 1,
          "modbusDataType": "int16SignedAB"
        },
        {
          "propertyPath": "volume",
          "modbusDataAddress": 1299,
          "modbusDataAccess": "holdingregister",
          "modbusSlave": 5,
          "modbusDataLen": 2,
          "modbusDataType": "ieeefloat32ABCD"
        },
        {
          "propertyPath": "status",
          "modbusDataAddress": 1199,
          "modbusDataAccess": "coil",
          "modbusSlave": 5,
          "modbusDataLen": 1,
          "modbusDataType": "int8Signed"
        }
      ]
    },
    "ownerName": "admin",
    "tableName": "modbusTableTCP",
    "retentionPolicy": "autoPurge",
    "retentionPeriod": 30,
    "retentionUnit": "day",
    "metadata": {}
  }
}

Responses

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,
              "modbusSlave": 5,
              "modbusDataLen": 1
            }
          ]
        },
        "tableName": "modbusTableTCP"
      },
      "requestId": "00000011",
      "debug": "max"
    }
  },
  "errorCode": 12012,
  "errorMessage": "There is already an integration with name of [modbusTCP]."
}

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

.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

.modbusDataAddress

specifies a particular data address

Required - No default value

int16

0 to 65535

settings

.propertyMapList

.modbusDataAccess

specifies the type of data structure to access

Required - No default value

string

"coil"

"discreteinput"

"holdingregister"

"inputregister"

settings

.propertyMapList

.modbusSlave

specifies a slave number for the Modbus controller in order to manage multiple devices that are using the same IP address.

The IP address plus the slave number uniquely identifies the device.

Required - No default value

int16

1 to 255

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"

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