Skip to main content

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.

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

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

specifies the protocol used to connect to the Modbus server

Required - No default value

string

"TCP"
"RTU"
settings
.modbusServer

specifies the IP/hostname of the Modbus device

Required - No default value

string

settings
.modbusServerPort

specifies the IP Port for the Modbus device for modbusTCP

Required - No default value

int16

0 to 65535

settings
.modbusDataCollectionIntervalMilliseconds

specifies how often the data should be requested in milliseconds

10000

int32

0 to 2147483647

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 247

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"


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