API reference
Modbus connector programming specifications
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",
"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": "' + 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": "register",
"modbusSlave": 5,
"modbusDataLen": 1,
"modbusDataType": "int16SignedAB"
},
{
"propertyPath": "volume",
"modbusDataAddress": 1299,
"modbusDataAccess": "register",
"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": 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.
"params" properties summaryProperty | Description | Default | Type | Limits | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
serviceName | specifies which type of input to create | Required - No default value | string |
| |||||||||||||||||||||||||||||||||||||||||||||
settings | specifies properties needed to configure the data source of the input. | Required - No default value | array of objects | ||||||||||||||||||||||||||||||||||||||||||||||
| specifies the protocol used to connect to the Modbus server | Required - No default value | string |
| |||||||||||||||||||||||||||||||||||||||||||||
| specifies the IP/hostname of the Modbus device | Required - No default value | string | ||||||||||||||||||||||||||||||||||||||||||||||
| specifies the IP Port for the Modbus device for modbusTCP | Required - No default value | int16 |
| |||||||||||||||||||||||||||||||||||||||||||||
| specifies how often the data should be requested in milliseconds |
| int32 |
| |||||||||||||||||||||||||||||||||||||||||||||
| specifies properties that represent the data being requested | Required - No default value | array of objects | ||||||||||||||||||||||||||||||||||||||||||||||
| specifies the JSON property that this data will be identified by | Required - No default value | string | ||||||||||||||||||||||||||||||||||||||||||||||
| specifies a particular data address | Required - No default value | int16 |
| |||||||||||||||||||||||||||||||||||||||||||||
| specifies the name of the Modbus variable for this data | Required - No default value | string |
Note: A register is one or more bytes, and a coil is one bit. | |||||||||||||||||||||||||||||||||||||||||||||
| 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 |
| |||||||||||||||||||||||||||||||||||||||||||||
| 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 |
| |||||||||||||||||||||||||||||||||||||||||||||
| spedivies 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 |
|