Skip to main content

Modbus API reference

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.

Set the Modbus TCP service

  1. Navigate to the config folder.

  2. Open the services.json configuration file in the config folder.

  3. Enable or disable the Modbus TCP service services by editing the "modbus" block of the "integrationServices" object.

    1. Set the "enabled" property to true to enable the Modbus TCP service.

      OR set the "enabled" property to false to disable the Modbus TCP service.

      {
      	"serviceName": "modbus",
      	"serviceLibrary": "modbusservice.dll",
      	"enabled": true
      }
      
    2. Save any changes.

    3. Restart the server for the change to take effect.

Examples

Note

The FairCom API uses the "createInput" action to define the specifics of a Modbus device and the desired data. See createInput for full documentation on the "createInput" action.

{
  "authToken": "<yourAuthTokenHere>",
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus",
    "settings": {
      "modbusProtocol": "TCP",
      "modbusServer": "127.0.0.1",
      "modbusServerPort": 1505,
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "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",
          "modbusDataAddress": 1199,
          "modbusSlave": 5,
          "modbusDataLen": 1
        }
      ]
    },
    "tableName": "modbusTableRTU"
  }
}
{
  "authToken": "<yourAuthTokenHere>",
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus",
    "settings": {
      "modbusProtocol": "TCP",
      "modbusServer": "127.0.0.1",
      "modbusServerPort": 1505,
      "modbusDataCollectionIntervalMilliseconds": 15000,
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "modbusDataAddress": 1199,
          "modbusDataAccess": "register",
          "modbusSlave": 5,
          "modbusDataLen": 1
        },
        {
          "propertyPath": "volume",
          "modbusDataAddress": 1299,
          "modbusDataAccess": "register",
          "modbusSlave": 5,
          "modbusByteOrder": "ABCD",
          "modbusDataLen": 2
        },
        {
          "propertyPath": "status",
          "modbusDataAddress": 1199,
          "modbusDataAccess": "coil",
          "modbusSlave": 5,
          "modbusDataLen": 1
        }
      ]
    },
    "ownerName": "admin",
    "tableName": "modbusTableTCP",
    "retentionPolicy": "autoPurge",
    "retentionPeriod": 30,
    "retentionUnit": "day",
    "transformName": "transform_modbus1",
    "metadata": {
    }
  }
}

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Note

Modbus utilizes the "createInput" action to define the specifics of the Modbus server and the desired data. For complete information on the "createInput" action, see "createInput".

Property summary

Table 1. "params" property summaries

Property

Description

Default

Type

Limits

"inputName"

contains the unique name of an input

Required - No default value

string

Minimum length: 1
Maximum length: 64

"serviceName"

signifies which type of input to create

Note

Must be set to "modbus".

Required - No default value

string

"settings"

contains properties needed to configure the data source of the input

Required - No default value

array of objects



The "settings" property is an array of objects that contains properties needed to configure the data source of the input. It is required and has no default.

Property summary

Table 2. "settings" property summaries

Property

Description

Default

Type

Limits

"modbusProtocol"

specifies the protocol used to connect to the Modbus server

Required - No default value

string

"TCP"

"RTU"

"modbusServer"

contains the IP/hostname of the Modbus device

Required - No default value

string

"modbusServerPort"

contains the IP Port for the Modbus device for modbusTCP

Required - No default value

int16

0 - 65,535

"modbusDataCollectionIntervalMilliseconds"

defines how often the data should be requested in milliseconds

10,000

int32

0 - 2,147,483,647

"propertyMapList"

contains properties that represent the data being requested

Required - No default value

array of objects



"propertyMapList"

The "propertyMapList" property is an array of objects that contains properties that represent the data being requested. It is required and has no default.

Property summary
Table 3. "propertyMapList" property summaries

Property

Description

Default

Type

Limits

"propertyPath"

contains the JSON property that this data will be identified by

Required - No default value

string

"modbusDataAddress"

identifies a particular data address

Required - No default value

int16

0 - 65,535

"modbusDataAccess"

contains the name of the Modbus variable for this data

Required - No default value

string

"register"
"coil"

Note

A register is one or more bytes and a coil is one bit.

"modbusSlave"

identifies a particular slave in the case of a Modbus controller that managers multiple slaves via the same IP

Required - No default value

int16

1 - 247

"modbusDataLen"

represents the number of 2-byte registers needed to hold the data — for example, modbusDataLen*2 is data length in bytes (for instance, float numbers can require more than one register)

Required - No default value

integer

1
2
4

"modbusByteOrder"

represents the order of significant bytes in floating point numerical data

"ABCD"

string

"ABCD"
"DCBA"
"BADC"
"CDAB"