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.

Note A connector is a bridge between a device/software and an integration table.

Request examples

Note The FairCom createInput JSON action is used to define the specifics of a connector device and the desired data.

Minimal

{
  "action": "createInput",
  "params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus",
    "thingName": "PLC 74",
    "settings": {
      "modbusProtocol": "TCP",
      "modbusServer": "127.0.0.1",
      "modbusServerPort": 502,
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "modbusDataAccess": "holdingregister",
          "modbusDataAddress": 1199,
          "modbusUnitId": 5,
          "modbusDataLen": 1
        }
      ]
    },
    "tableName": "modbusTableTCP"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

RTU

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "modbusRTU",
    "serviceName": "modbus",
    "dataPersistenceStrategy": "onChange", 
    "dataCollectionIntervalMilliseconds": 5000,
    "immediatelyCollectDataOnStart": true,
    "dataCollectionBufferCount": 2,
    "settings": {
      "modbusProtocol": "RTU",
      "modbusSerialPort": "COM2",
      "modbusBaudRate": 19200,
      "modbusParity": "None",
      "modbusDataBits": 8,
      "modbusStopBits": 2,
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "modbusDataAccess": "holdingregister",
          "modbusDataAddress": 1199,
          "modbusUnitId": 5,
          "modbusDataLen": 1
        }
      ]
    },
    "tableName": "modbusTableRTU"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus",
    "thingName": "PLC 74",
    "dataCollectionIntervalMilliseconds": 5000,
    "settings": {
      "modbusProtocol": "TCP",
      "modbusServer": "127.0.0.1",
      "modbusServerPort": 502,
      "modbusDataAddressType": "zeroBased",
      "propertyMapList": [
        {
          "propertyPath": "temperature",  //Deprecated
          "modbusDataAddress": 1199,
          "modbusDataAccess": "holdingregister",
          "modbusUnitId": 1,
          "modbusDataType": "int16SignedAB"
        },
        {
          "tagName": "status",
          "modbusDataAddress": 1199,
          "modbusDataAccess": "inputregister",
          "modbusUnitId": 1,
          "modbusDataType": "int8Signed"
        },
        {
          "tagId": 18,
          "modbusDataAddress": 1299,
          "modbusDataAccess": "coil",
          "modbusUnitId": 1,
          "modbusDataType": "ieeeFloat32ABCD"
        },
        {
          "propertyPath": "pressure",
          "modbusDataAddress": 1499,
          "modbusDataAccess": "inputregister",
          "modbusUnitId": 1,
          "modbusDataType": "int16SignedAB",
          "modbusConvertToFloat": "divideByInteger",
          "modbusDecimalDigits": 2,
          "modbusDivisor": 1000
        },
        {
          "propertyPath": "humidity",
          "modbusDataAddress": 1599,
          "modbusDataAccess": "holdingregister",
          "modbusUnitId": 1,
          "modbusDataType": "int16SignedAB",
          "modbusDecimalDigits": 2,
          "modbusConvertToFloat": "appendAdjacentRegisters"
        },
        {
          "propertyPath": "sos",
          "modbusDataAccess": "discreteinput",
          "modbusDataAddress": 1024,
          "modbusDataType": "bitBoolean",
          "bitBooleanZeroValue": false,
          "bitStartPosition": 0
        },
        {
          "propertyPath": "batteryHealth",
          "modbusDataAccess": "discreteinput",
          "modbusDataAddress": 1024,
          "modbusDataType": "bitString",
          "bitStringZeroValue": "healthy",
          "bitStringOneValue": "unhealthy",
          "bitStartPosition": 1
        },
        {
          "propertyPath": "voltageLevel",
          "modbusDataAccess": "holdingregister",
          "modbusDataAddress": 1024,
          "modbusDataType": "bitInt",
          "bitStartPosition": 2,
          "bitEndPosition": 9,
          "bitReverseOrder": false,
          "bitIntSigned": false,
          "bitLittleEndian": false
        },
        {
          "propertyPath": "batteryStatus",
          "modbusDataAccess": "holdingregister",
          "modbusDataAddress": 1024,
          "modbusDataType": "bitEnum",
          "bitStartPosition": 10,
          "bitEndPosition": 12,
          "bitReverseOrder": false,
          "bitLittleEndian": false,
          "bitEnumValues": [
            "0-low voltage error",
            "1-low voltage",
            "2-normal voltage",
            "3-high voltage",
            "4-high voltage error"
          ]
        }
      ]
    },
    "ownerName": "admin",
    "tableName": "modbusTableTCP",
    "retentionPolicy": "autoPurge",
    "retentionPeriod": 30,
    "retentionUnit": "day",
    "metadata": {
    }
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

A response to a request is "0" when successful. A non-zero value response indicates an error occurred.

Successful

{
    "result": {},
    "requestId": "00000007",
    "errorCode": 0,
    "errorMessage": ""
}

Error

{
  "result": {},
  "requestId": "00000011",
  "debugInfo": {
    "request": {
      "api": "hub",
      "action": "createInput",
      "params": {
        "inputName": "modbusTCP",
        "serviceName": "modbus",
        "settings": {
          "modbusProtocol": "TCP",
          "modbusServer": "127.0.0.1",
          "modbusServerPort": 502,
          "propertyMapList": [
            {
              "propertyPath": "temperature",
              "modbusDataAddress": "holdingregister",
              "modbusDataAddress": 1199,
              "modbusUnitId": 5,
              "modbusDataLen": 1
            }
          ]
        },
        "tableName": "modbusTableTCP"
      },
      "requestId": "00000011",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 12012,
  "errorMessage": "There is already an integration with name of [modbusTCP].",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Properties

Request properties (`"params"`)

Property	Description	Default	Type	Limits (inclusive)
dataCollectionBufferCount	The `"dataCollectionBufferCount"` property 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.	Optional with default of `1`	integer	`1` to `65535`
dataCollectionIntervalMilliseconds	The `"dataCollectionIntervalMilliseconds"` property schedules the connector to collect data periodically using the specified number of milliseconds.	Optional with default of `10000` (10 seconds).	integer	`0` and negative values are invalid.
dataPersistenceStrategy	The `"dataPersistenceStrategy"` property controls when a connector writes collected data to a record in the input table specified by `"tableName"`. The `"onSchedule"` setting causes the connector to persist each collected value, which occurs on the schedule set by the `"dataCollectionIntervalMilliseconds"` property. This setting is useful for continuously collecting device data for trend analysis and machine learning. The `"onChange"` setting causes the connector to collect data on the schedule set by the `"dataCollectionIntervalMilliseconds"` property, but it only persists data when it changes. This allows the connector to detect and store data changes as events, such as alerts and status updates. This setting greatly reduces data storage for infrequently changing telemetry, such as changes to a temperature sensor. Note The connector misses events when its data collection schedule is not frequent enough to see data changes. Thus, the `"onChange"` setting makes a polling protocol, such as Modbus, behave like a push protocol, but it is not a push protocol like MQTT.	Optional with default of `"onSchedule"`	string	`"onSchedule"` `"onChange"`
description	The `"description"` property assigns a description to a connector.	Optional with default of `""`	string	1 to 512 bytes
enabled	The `"enabled"` property turns on or off an input or output connector. Thus, it pauses or starts data collection or delivery.	Optional with default of `true`	Boolean	`true` `false`
enabledFilter	The `"enabledFilter"` property returns input connections that are enabled or not. Omit or set to `null` to match all connections.	Optional with default of `null`	Boolean	`true` `false`
immediatelyCollectDataOnStart	The `"immediatelyCollectDataOnStart"` property controls how a connector first collects data after being started. When `true`, it immediately collects and stores data and thereafter collects data according to the strategy specified in `"dataPersistenceStrategy"`. In other words, it ignores the `"dataPersistenceStrategy"` for the initial data collection event and unconditionally stores the first set of data it collects. This setting allows subscribers to receive an initial data collection message each time the server or connector starts, which is useful for systems that display live status information. When `false`, which is the default, it collects data according to the strategy specified in `"dataPersistenceStrategy"`. For example, when the `"dataPersistenceStrategy"` is `"onChange"`, the connector collects data on a schedule and persists it only when the data changes - even after a restart.	Optional with default of `false`	Boolean	`true` `false`
inputName	The `"inputName"` property specifies the unique name of an input. A FairCom generated name follows the pattern `"Input #n from <pluginName> to <databaseName>.<ownerName>.<tableName>"`. "params": { "inputName": "modbusTCP", "serviceName": "modbus" }	Required - No default value	string	1 to 100 bytes
metadata	The `"metadata"` property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages.	Optional with default of `{}`	object	0 or more key/value pairs
ownerName	The `"ownerName"` property specifies the account that owns an object, such as a table or code package. See `"createSession"` and the `"defaultOwnerName"` property for more details. You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code. It is an error to set `"ownerName"` to the empty string `""`. If no default owner is specified during `"createSession"`, the server sets the `"defaultOwnerName"` to the `"defaultOwnerName"` value specified in the services.json file.	Optional with default of the session's `"defaultOwnerName"` property	string	1 to 64 bytes
purpose	The `"purpose"` property specifies the purpose of the thing. You can use it for fast partial lookups and filtering.	Optional with default of `"unknown"`	string	1 to 64 bytes Values are managed in the Label API with the group `"faircom/edge/purpose"`.
retentionPeriod	The `"retentionPeriod"` property specifies how many units of data to retain. It refers to the unit of time specified by the `"retentionUnit"` property. For more details, see `"retentionPeriod"`.	Optional with default of `30`	integer	`1` to `100`
retentionPolicy	The `"retentionPolicy"` property controls how messages are persisted. If not specified, the default found in the `services.json` file is used. Initially, it is `"autoPurge"`. retentionPolicy values: `"autoPurge"` This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files. `"neverPurge"` This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.	Optional with default of `"autoPurge"`	string	`"autoPurge"` `"neverPurge"`
retentionUnit	The `"retentionUnit"` property specifies a unit of time that the server will use to purge expired messages. For example, if you want a week's worth of messages to be purged once a week, set `"retentionUnit"` to `"week"`. This property is optional. If not specified, the default found in the `services.json` file is used. Initially, it is `"week"`. This property is used in concert with `"retentionPeriod"` to determine retention time. `"retentionUnit" values:` `"minute"` `"hour"` `"day"` `"week"` `"month"` `"year"` `"forever"` Note For best performance, set the `"retentionUnit"` to a value that keeps `"retentionPeriod"` between `5` and `30`. When you set `"retentionUnit"` property to `"forever"` the server will not purge messages. This setting is the same as setting `"retentionPolicy"` to `"neverPurge"`. The `"retentionUnit"` and `"retentionPeriod"` properties are used only when the `"retentionPolicy"` is set to `"autoPurge"`.	Optional with default of `"day"`	string	`"minute"` `"hour"` `"day"` `"week"` `"month"` `"year"`
runningFilter	The `"runningFilter"` property returns input connections that are running or not. Omit or set to `null` to match all connections.	Optional with default of `null`	Boolean	`true` `false`
serviceName	The `"serviceName"` property contains the name of a FairCom input or output service. See the `"params"` topic of each specific service for the requirements of this property. `The following services are available as of the V5 release:` `"MODBUS"` `"SIEMENSUDT2JSON"` `"OPCUA"` Note The SQL, JSON RPC, and REST services can automatically query any integration table in FairCom's servers without requiring configuration. MQTT always represents both input and output services. This is because once a topic is created and assigned to an integration table, any MQTT client can publish messages to it and subscribe to those messages.	Required - No default value	string	1 to 64 bytes
settings	The `"settings"` property contains properties that are specific for each connector type. Settings for Modbus are different than settings for OPC UA, and so forth. See the API reference `"params"` property of each connector for details of the `"settings"` property for that connector.	Optional with default of `{}`	object	See these pages for connector specific properties: Allen-Bradley "params" Modbus "params" OPC UA "settings" Siemens S7 "params"
settings .modbusBaudRate	The `"modbusBaudRate"` property (RTU only) specifies the baud rate of the communication (`9600`, `19200`, `57600`, `115200`, and so forth).	Optional with default of `19200`	int16	Any baud rate
settings .modbusDataAddressType	The `"modbusDataAddressType"` property specifies if the `modbusDataAddress` is zero-based or one-based.	Optional with default of `"zeroBased"`	string	`"zeroBased"` `"oneBased"`
settings .modbusDataBits	The `"modbusDataBits"` property (RTU only) specifies the number of bits of data.	Optional with default of `8`	int16	`5`, `6`, `7`, or `8`
settings .modbusParity	The `"modbusParity"` property (RTU only) specifies the data parity.	Optional with default of `"even"`	string	`"none"`, `"even"`, `"odd"`
settings .modbusProtocol	The `"modbusProtocol"` property specifies the protocol used to connect to the Modbus server.	Required - No default value	string	`"TCP"` `"RTU"`
settings .modbusSerialPort	The `"modbusSerialPort"` property (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	No limit
settings .modbusServer	The `"modbusServer"` property (TCP only) specifies the IP/hostname of the Modbus device.	Required - No default value	string	No limit
settings .modbusServerPort	The `"modbusServerPort"` property (TCP only) specifies the IP Port for the Modbus device for modbusTCP.	Required - No default value	int16	`0` to `65535`
settings .modbusStopBits	The `"modbusStopBits"` property (RTU only) specifies the bits of stop.	Optional with default of `1`	int16	`1` or `2`
settings .propertyMapList	The `"propertyMapList"` property specifies which data the connector requests and where to put it in the generated JSON.	Required - No default value	array of objects	zero or more objects containing zero or more of the following properties: `"bitBooleanZeroValue"` `"bitEndPosition"` `"bitEnumValues"` `"bitIntSigned"` `"bitLittleEndian"` `"bitReverseOrder"` `"bitStartPosition"` `"bitStringOneValue"` `"bitStringZeroValue"` `"modbusConvertToFloat"` `"modbusDataAccess"` `"modbusDataAddress"` `"modbusDataLen"` `"modbusDataType"` `"modbusDataType"` `"modbusDecimalDigits"` `"modbusDivisor"` `"modbusUnitId"` `"propertyPath"`
settings propertyMapList .bitBooleanZeroValue	The `"bitBooleanZeroValue"` property only applies when the `"modbusDataType"` property is set to `"bitBoolean"`. When set to `true`, the connector maps a bit value of `1` to `false` and `0` to `true`.	Optional with default of `false`	Boolean	`true` `false`
settings propertyMapList .bitEndPosition	The `"bitEndPosition"` must be greater than or equal to `"modbusStartBitPosition"` when present. When omitted, it defaults to the value of the `"bitStartPosition"` property. When `"modbusDataType"` is `"bitInt"`, `"bitEndPosition"` is required. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. The server converts these bits into an integer number before writing the value to the record. You can optionally use the `"bitIntSigned"`, `"bitLittleEndian"`, and `"bitReversedOrder"` properties to change how the server converts the value into an integer. You can optionally use `"bitIntSigned"`, `"bitLittleEndian",` and `"bitReversedOrder"` to control how the server interprets the bits when it converts them into an integer number. When `"modbusDataType"` is `"bitEnum"`, `"bitEndPosition"` is required. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. The server converts these bits into an unsigned integer number before writing the value to the record. You can optionally use the `"bitLittleEndian"` and `"bitReversedOrder"` properties to change how the server converts the value into an integer. When `"modbusDataType"` is `"bitBoolean"`, `"bitEndPosition"` is not allowed. For examples, see Modbus data types.	Required if `"modbusDataType"` is `"bitInt"` or `"bitEnum"`. Defaults to the value of the `"bitStartPosition"`	int16	`0` to `15`
settings propertyMapList .bitEnumValues	The `"bitEnumValues"` property specifies enumerated values that will be used to convert bits into readable text. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. The server converts these bits into an unsigned integer number, looks up the string in the `"bitEnumValues"` array, and writes the enumerated string value on the record. The server sets the value to `null` if the `"bitEnumValues"` array does not contain a string value corresponding to the integer value. You can optionally use the `"bitLittleEndian"` and `"bitReversedOrder"` properties to change how the server converts the value into an integer. For examples, see Modbus data types.	Required if `"modbusDataType"` is `"bitEnum"`	array of strings	1 or more strings
settings propertyMapList .bitIntSigned	The `"bitIntSigned"` property determines if bits will be interpreted as a signed integer value. When `"modbusDataType"` is `"bitInt"`, `"bitIntSigned"` is optional. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. If `"bitIntSigned"` is `true`, the server interprets these bits as a signed integer number before writing the value to the record; otherwise, it interprets them as an unsigned integer. When `"modbusDataType"` is `"bitBoolean"`, `"bitIntSigned"` is not allowed. When `"modbusDataType"` is `"bitEnum"`, `"bitIntSigned"` is not allowed. For examples, see Modbus data types.	Optional with default of `false`	Boolean	`true` `false`
settings propertyMapList .bitLittleEndian	The `"bitLittleEndian"` property determines how the connector interprets a range of nine or more bits. When set to `true`, the connector interprets a range of nine or more bits in little-endian order instead of big-endian order. A range of eight bits or less is unaffected by endian status. The Modbus `"int16SignedBA"` or `"int16UnsignedBA"` data types are in little-endian order. When `"modbusDataType"` is `"bitInt"`, `"bitLittleEndian"` is optional. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. If `"bitLittleEndian"` is `true`, the server interprets these bits as a little-endian number before writing the value to the record; otherwise, it interprets the bits as a big-endian number. When `"modbusDataType"` is `"bitEnum"`, `"bitLittleEndian"` is optional. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. If `"bitLittleEndian"` is `true`, the server interprets the bit order in little-endian order before converting each bit to an enumerated value and writing it to the record; otherwise, it interprets the bits in big-endian number. When `"modbusDataType"` is `"bitBoolean"`, `"bitLittleEndian"` is not allowed. For examples, see Modbus data types.	Optional with default of `false`	Boolean	`true` `false`
settings propertyMapList .bitReverseOrder	The `"bitReverseOrder"` property specifies whether or not the bit values will be read in reverse order. When `true`, the connector assigns bit values to the integer value starting from the end bit position to the start bit position; otherwise, it starts with the start bit position. It places bit values into the integer, starting from the rightmost bit to the leftmost. When `"modbusDataType"` is `"bitInt"`, `"bitReversedOrder"` is optional. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. If `"bitReversedOrder"` is `true`, the server interprets these bits in reverse order before writing the value to the record; otherwise, it interprets the bits in normal order. When `"modbusDataType"` is `"bitEnum"`, `"bitReversedOrder"` is optional. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. If `"bitReversedOrder"` is `true`, the server interprets these bits in reverse order before writing the value to the record; otherwise, it interprets the bits in normal order. For example, if `"bitReverseOrder"` is `false`, `"bitStartPosition"` is `5`, and `"bitEndPosition"` is `6`, the connector works its way from the end position to the starting position, setting bits in the integer from right to left. For example, it takes the bit value at the bit end position and sets it into the rightmost bit in the integer. It then takes the bit value at the next-to-last position and sets it to the left of the previous bit. Thus, if `1` is the bit value in the Modbus register at bit position `5` and `0` is the value of bit position `6`, the resulting binary integer value is `0000 0010`. Given the same bit values, if `"bitReverseOrder"` is `true`, the resulting integer value is `0000 0001`. When `"modbusDataType"` is `"bitBoolean"`, `"bitReversedOrder"` is not allowed. For examples, see Modbus data types.	Optional with default of `false`	Boolean	`true` `false`
settings propertyMapList .bitStartPosition	The `"bitStartPosition"` property specifies where bits will start to be collected from. When `"modbusDataType"` is `"bitBoolean"`, `"bitStartPosition"` is required. The server retrieves 16 bits at the address specified by `"modbusDataAddress"` and converts the bit value at the specified starting offset to a boolean value. The server converts a zero bit to `false` and a one bit to `true` before writing the value to the record. When `"modbusDataType"` is `"bitInt"`, `"bitStartPosition"` is required. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. The server converts these bits into an integer number before writing the value to the record. You can optionally use the `"bitIntSigned"`, `"bitLittleEndian"`, and `"bitReversedOrder"` properties to change how the server converts the value into an integer. You can optionally use `"bitIntSigned"`, `"bitLittleEndian"`, and `"bitReversedOrder"` to control how the server interprets the bits when it converts them into an integer number. When `"modbusDataType"` is `"bitEnum"`, `"bitStartPosition"` is required. The server retrieves bits from the address specified by `"modbusDataAddress"`. The bits start from the offset specified by `"bitStartPosition"` and end at the offset defined by `"bitEndPosition"`. The server converts these bits into an unsigned integer number, looks up the string in the `"bitEnumValues"` array, and writes the enumerated string value on the record. You can optionally use the `"bitLittleEndian"` and `"bitReversedOrder"` properties to change how the server converts the value into an integer. For examples, see Modbus data types.	Required if modbusDataType is , `"bitString"`, `"bitInt"`, or `"bitEnum"`	int16	`0` to `15`
settings propertyMapList .bitStringOneValue	The `"bitStringOneValue"` property is used to specify the JSON key. When the bit value is `1`, the connector assigns the value of `"bitStringOneValue"` to the JSON key defined by `"propertyPath"`. You may set it to any string value, including the empty string `""`, `"null"`, `"true"`, `"false"`, `"2"`, or `"-9"`. You cannot set it to a non-string value, such as the JSON symbols `null`, `true`, `false`, or a number like `2`, or `-9`. `"bitStringOneValue"` is required when the data type is `"bitString"`. The server retrieves an integer from the address specified by `"modbusDataAddress"`. It extracts one bit starting from the offset specified by `"bitStartPosition"`. The server maps a zero bit value to the string specified by `"bitStringZeroValue"` or maps a one value to the string specified by the `"bitStringOneValue"` property and writes the string into the record. The `"bitStringOneValue"` property is only allowed when the data type is `"bitString"`. For examples, see Modbus data types.	Required if `"modbusDataType"` is `"bitString"`	string	No limit
settings propertyMapList .bitStringZeroValue	The `"bitStringZeroValue"` property is used to specify the JSON key. When the bit value is `0`, the connector assigns the value of `"bitStringZeroValue"` to the JSON key defined by `"propertyPath"`. You may set it to any string value, including the empty string `""`, `"null"`, `"true"`, `"false"`, `"2"`, or `"-9"`. You cannot set it to a non-string value, such as the JSON symbols `null`, `true`, `false`, or a number like `2`, or `-9`. `"bitStringZeroValue"` is required when the data type is `"bitString"`. The server retrieves an integer from the address specified by `"modbusDataAddress"`. It extracts one bit starting from the offset specified by `"bitStartPosition"`. The server maps a zero bit value to the string specified by `"bitStringZeroValue"` or maps a one value to the string specified by the `"bitStringOneValue"` property and writes the string into the record. The `"bitStringZeroValue"` property is only allowed when the data type is `"bitString"`. For examples, see Modbus data types.	Required if `"modbusDataType"` is `"bitString"`	string	No limit
settings propertyMapList .modbusConvertToFloat	The `"modbusConvertToFloat"` property causes the connector to convert one or two register values into a JSON floating point number.	Optional with default of `"no"`	string	`"no"` `"divideByInteger"` `"appendAdjacentRegisters"` `"appendAdjacentRegistersReversed"`
settings propertyMapList .modbusDataAccess	The `"modbusDataAccess"` property specifies the type of data structure to access. `"coil"` - 1 bit read-write `"discreteinput"` - 1 bit read-only `"holdingregister"` - 2 byte word read-write `"inputregister"` - 2 byte word read-only	Required - No default value	string	`"coil"` `"discreteinput"` `"holdingregister"` `"inputregister"`
settings propertyMapList .modbusDataAddress	The `"modbusDataAddress"` property specifies where the Modbus protocol should read or write a value to a memory address on a device. 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`.	Required - No default value	int16	`0` to `65536`
settings propertyMapList .modbusDataLen	The `"modbusDataLen"` property 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	integer	`1`, `2`, or `4`
settings propertyMapList .modbusDataType	The `"modbusDataType"` property 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 with default of `""`	string	Any Modbus Data Type
settings propertyMapList .modbusDecimalDigits	The `"modbusDecimalDigits"` property specifies the number of floating-point fractional digits to retain in a floating-point number. Set it to null to retain all digits. Valid values are `0`, `1`, `2`, `3`, `4`, or `5`. The server truncates the floating-point number to the specified number of digits.	Optional with default of `2`	integer	`1` to `5`
settings propertyMapList .modbusDivisor	The `"modbusDivisor"` property specifies the divisor the server uses to convert an integer value to a float. Use it when you set the `"modbusDataType"` to one of the integer types, and the server will convert the value to a floating point before writing it to the record.	Required if `"modbusConvertToFloat"` is `"divideByInteger"`. Otherwise defaults to 1	integer	`1` to `65536` Typical values are `10`, `100`, `1000`, and `10000`
settings propertyMapList .modbusUnitId	The `"modbusUnitId"` property 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.	Optional with default of `1`	int16	`0` to `255`
settings propertyMapList .propertyPath	The `"propertyPath"` property specifies the JSON path in the JSON document where the connector puts the data it collects. It is mutually exclusive with the `"tagName"` and `"tagId"` properties.	Required - No default value	string	JSON path
settings propertyMapList .tagId	The `"tagId"` property associates a tag with a value being collected by a connector. It is mutually exclusive with the `"tagName"` and `"propertyPath"` properties. See tagId for more details.	Conditional - No default value	integer	If present, it must contain the ID of an existing tag, which is an integer from `0` to `9223372036854770000`. Note FairCom recommends using this property instead of `"propertyPath"`.
settings propertyMapList .tagName	The `"tagName"` property associates a tag with a value being collected by a connector. It is mutually exclusive with the `"tagId"` and `"propertyPath"` properties. See tagName for more details.	Conditional - No default value	string	If present, it must contain the name of an existing tag. Note FairCom recommends using this property instead of `"propertyPath"`.
status	The `"status"` property assigns an active or inactive status to a thing. An inactive status is like a soft delete.	Optional with default of "active"	string enum	`"active"` `"inactive"`
tableName	The `"tableName"` property contains the unique, user-defined name of a table. The table name must start with an upper or lowercase letter, must not contain special characters other than underscore `"_"`, and can include a mix of upper-lower case characters, but are treated as case-insensitive. "params": { "tableName": "ctreeTable" }	Required - No default value	string	1 to 64 bytes
thingId	The `"thingId"` property associates a connector with a device or software application. It is mutually exclusive with the `"thingName"` property. See thingId for more details.	Optional with default of `null`	integer	If present, it must contain the ID of an existing thing, which is an integer form `0` to `9223372036854770000`.
thingName	The `"thingName"` property associates a connector with a device or software application. It is mutually exclusive with the `"thingId"` property. See thingName for more details.	Optional with default of `null`	string	1 to 64 bytes

Response properties (`"result"`)

Property	Description	Type	Limits (inclusive)
data	The `"data"` property contains a response message. Its contents are defined by the action. It is an empty array when no results are available. The following is an example of the data property from a code package action. "result": { "data": [ { "codeId": 6, "databaseName": "faircom", "ownerName": "admin", "codeName": "convertAndCategorizeTemperature", "codeVersion": 1, "clonedCodeId": 1, "codeStatus": "active", "codeLanguage": "javascript", "serviceName": "javascript", "codeType": "module", "description": "optional new description", "metadata": {}, "createdBy": "ADMIN", "createdOn": "2025-08-25T21:48:38.109", "updatedBy": "ADMIN", "updatedOn": "2025-08-25T21:48:38.109", "comment": "Cloned from convertTemperature", "codeFormat": "utf8" }, ]	array of objects	The action determines its contents.
data .enabled	The `"enabled"` property is `true` when a connector is allowed to connect to a device. It is `false` when a connector will not attempt to connect to the device.	boolean	`true` `false`
data .running	The `"running"` property is `true` when an input connector is collecting data or an output connector is delivering data; otherwise, it is `false`. A disabled connector will never be running. An enabled connector may or may not be running.	Boolean	`true` `false`
data .settings	The `"settings"` property contains properties that are specific for each connector type. Settings for Modbus are different than settings for OPC UA, and so forth. See the API reference `"params"` property of each connector for details of the `"settings"` property for that connector.	object	See these pages for connector specific properties: Allen-Bradley "params" Modbus "params" OPC UA "settings" Siemens S7 "params"
data settings .propertyMapList	The `"propertyMapList"` property specifies which data the connector requests and where to put it in the generated JSON.	array of objects	See these pages for connector specific properties: Allen-Bradley "params" Modbus "params" OPC UA "settings" Siemens S7 "params"
data settings propertyMapList .propertyPath	The `"propertyPath"` property specifies the JSON path in the JSON document where the connector puts the data it collects. It is mutually exclusive with the `"tagName"` and `"tagId"` properties.	string	JSON path
data settings propertyMapList .tagId	The `"tagId"` property associates a tag with a value being collected by a connector. It is mutually exclusive with the `"tagName"` and `"propertyPath"` properties. See tagId for more details.	integer	If present, it must contain the ID of an existing tag, which is an integer from `0` to `9223372036854770000`. Note FairCom recommends using this property instead of `"propertyPath"`.
data settings propertyMapList .tagName	The `"tagName"` property associates a tag with a value being collected by a connector. It is mutually exclusive with the `"tagId"` and `"propertyPath"` properties. See tagName for more details.	string	If present, it must contain the name of an existing tag. Note FairCom recommends using this property instead of `"propertyPath"`.
data .stopCode	The `"stopCode"` property is `0` when the connector is successfully connected to its device or software; otherwise, it is non-zero.	integer	`-2147483648` to `2147483647`
data .stopReason	The `"stopReason"` property is `""` when the input connector is collecting data; otherwise, it is a non-empty string.	string	0 to 256 bytes
data .thingId	The `"thingId"` property associates a connector with a device or software application. It is mutually exclusive with the `"thingName"` property. See thingId for more details.	integer	If present, it must contain the ID of an existing thing, which is an integer form `0` to `9223372036854770000`.
data .thingName	The `"thingName"` property associates a connector with a device or software application. It is mutually exclusive with the `"thingId"` property. See thingName for more details.	string	1 to 64 bytes

API reference

Request examples

Minimal

RTU

Maximal

Response examples

Successful

Error

Properties

Request properties ("params")

dataCollectionBufferCount

dataCollectionIntervalMilliseconds

dataPersistenceStrategy

description

enabled

enabledFilter

immediatelyCollectDataOnStart

inputName

metadata

ownerName

purpose

retentionPeriod

retentionPolicy

retentionUnit

runningFilter

serviceName

settings

.modbusBaudRate

.modbusDataAddressType

.modbusDataBits

.modbusParity

.modbusProtocol

.modbusSerialPort

.modbusServer

.modbusServerPort

.modbusStopBits

.propertyMapList

.bitBooleanZeroValue

.bitEndPosition

.bitEnumValues

.bitIntSigned

.bitLittleEndian

.bitReverseOrder

.bitStartPosition

.bitStringOneValue

.bitStringZeroValue

.modbusConvertToFloat

.modbusDataAccess

.modbusDataAddress

.modbusDataLen

.modbusDataType

.modbusDecimalDigits

.modbusDivisor

.modbusUnitId

.propertyPath

.tagId

.tagName

status

tableName

thingId

thingName

Response properties ("result")

data

.enabled

.running

.settings

.propertyMapList

.propertyPath

.tagId

.tagName

.stopCode

.stopReason

.thingId

.thingName

Was this article helpful?

Related Articles

Working With Resources (.NET)

Fields to JSON API reference

JSON to fields API reference

Request properties (`"params"`)

Response properties (`"result"`)