Skip to main content

API Reference

Allen-Bradley connector programming specifications

Abstract

FairCom provides specific API actions to configure the Allen-Bradley connector

FairCom provides specific API actions to configure the Allen-Bradley connector. Be sure to enable the Allen-Bradley service before requesting data from an Allen-Bradley service.

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":"abTest1",
      "serviceName":"ab",
      "tableName":"abTable1",
      "settings":{
         "dataCollectionIntervalMilliseconds":5000,
         "dataReadingTimeoutMilliseconds":5000,
         "plcAddress":"192.142.100.22",
         "plcType":"controllogix",
         "propertyMapList":[
            {
               "tagPath":"1,0",
               "tagName":"temperature",
               "tagType":"float32",
               "propertyPath":"temperature"
            }
         ]
      }
   },
   "requestId":"00000004"
}
         
{
   "authToken": "<yourAuthTokenHere>",
   "api":"hub",
   "action":"createInput",
   "params":{
      "inputName":"abTest1",
      "serviceName":"ab",
      "tableName":"abTable1",
      "settings":{
         "dataCollectionIntervalMilliseconds":1000,
         "dataReadingTimeoutMilliseconds":5000,
         "dataCollectionBufferCount":10,
         "plcAddress":"192.142.100.22",
         "plcType":"controllogix",
         "propertyMapList":[
            {
               "tagPath":"1,0",
               "tagName":"scada",
               "tagElementCount":10,
               "tagType":"int32",
               "propertyPath":"scada"
            },
            {
               "tagPath":"1,0",
               "tagName":"temperature",
               "tagType":"float32",
               "propertyPath":"temperature"
            },
            {
               "tagPath":"1,0",
               "tagName":"message",
               "tagType":"string",
               "tagSize":20,
               "propertyPath":"message"
            }
         ]
      }
   },
   "requestId":"00000004"
}
{
  "create_ts":"2023-09-19T20:37:12.678Z",
  "scada0":10,
  "scada1":20,
  "scada2":30,
  "scada3":40,
  "scada4":50,
  "scada5":60,
  "scada6":70,
  "scada7":80,
  "scada8":90,
  "scada9":100,
  "temperature":86.230003356933594,
  "message":"AB rocks            "
}

The Maximal request configures the Allen-Bradley connector to collect data from a ControlLogix PLC at address 192.142.100.22 every 5 seconds. It collects data from 3 tag addresses named "scada", "temperature", and "message" . If it cannot read the tags within 1 second, it returns a timeout error. 

In this example, the connector retrieved ten 32-bit integers from the PLC starting at the "scada" tag address and added each integer to the generated JSON as a separate property named "scadaN" where N is the zero-based array index number. In the PLC, the "scada" tag had an array containing the following ten integer values: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]. The generated JSON included the corresponding ten properties: "scada0":10, "scada1":20, "scada2":30, "scada3":40, "scada4":50, "scada5":60, "scada6":70, "scada7":80, "scada8":90, "scada9":100.

The connector also retrieved one Floating point number from the PLC starting at the tag address "temperature" and added it to the generated JSON as a property named "temperature". Because the connector retrieved only one value, it did not append an index number to the end of the "temperature" property name.  In the PLC, the "temperature" tag was a floating-point number 86.230003356933594. The generated JSON included the corresponding property "temperature":86.230003356933594.

The connector then retrieved a 20-byte string from the PLC starting at the tag address "message" and added it to the generated JSON as a property named "message". Because the connector retrieved only one value, it did not append an index number to the end of the "message" property name. In the PLC, the "message" tag was the 20-byte string "AB rocks            ". The generated JSON included the corresponding property "message":"AB rocks            ".

The connector receives the collected JSON data in the source_payload field of a JSON document, and inserts it in a record in the "abTable1" table.

"tagName" options

If you want to read an array starting in the middle, add the first position inside square brackets as part of the tag name.

For example, the following request values would generate the following retrieved data.

Request values

{
  "tagPath":"1,0",
  "tagName":"scada[4]",
  "tagElementCount":3,
  "tagType":"int32",
  "propertyPath":"scada"
}

Retrieved data

{
  "create_ts":"2023-09-26T19:01:39.714Z",
  "scada0":50,
  "scada1":60,
  "scada2":70
}

In this example, the "scada" tag represents an array in the PLC containing the following ten integer values: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]. The tag array is zero-based.

The first element is [0] so "tagName": "scada[4]" collects data at the 5th item in the array, which has the value of 50. Specifying "tagElementCount": 3 collects 3 items from the array.

The connector generates JSON containing the properties "scada0":50, "scada1":60, and "scada2":70. These properties correspond to the properties named "scada4":50, "scada5":60, and "scada6":70 in the results from the Maximal example.

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

Not yet available.

"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. Allen-Bradley specific connector "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

serviceName

specifies which type of input to create

Required - No default value

string

"ab"

settings

specifies properties needed to configure the data source of the input.

Required - No default value

array of objects

settings
.dataCollectionBufferCount

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:

1

integer

1 to 65535

settings
.dataCollectionIntervalMilliseconds

specifies the number of milliseconds to wait until reading PLC data again. For example, 15000 means 15 seconds.

10000

int32

0 and negative values are invalid.

settings
.dataReadingTimeoutMilliseconds

specifies the timeout in milliseconds while connecting and reading data from the PLC.

Optional:

1000

int32

0 and negative values are invalid.

settings
.plcAddress

specifies the IP address or hostname and optional port from the PLC, in the format IPaddress:Port, with Port being optional. 

Required - No default value

string

Examples:

172.16.0.1

172.16.0.1:4401

settings
.plcType

specifies the type of the PLC

Required - No default value

string

"controllogix"
"plc5"
"slc500"
"logixpccc"
"micro800"
"micrologix"
"omron-njnx"
settings
.propertyMapList

specifies which data the connector requests and where to put it in the generated JSON.

Required - No default value

array of objects

settings
.propertyMapList
.tagElementCount

specifies the number of elements in the tag. All tags are treated as arrays. Tags that are not arrays are considered to have a length of one element.

1

int32

0 and negative values are invalid.

settings
.propertyMapList
.tagName

specifies the full name of a tag, such as MyTag[10,42] for CIP-based PLCs. 

For  CIP-based PLCs, use the format Program:<program name>.<tag> .

<program name> is the program name in which the tag is created
<tag> is the name in the program.

Examples: Program:MyProgram.MyTag accesses the tag MyTag in the program MyProgram

PCCC-based PLC examples include N7:4, ST18:26, L20:2, MG14:6.en, B3:4/2, and so forth. Many common field name abbreviations are supported.

Required - No default value

string

settings
.propertyMapList
.tagPath

specifies additional connection information with the  format "p,s"

p is the communication Port Type

1 for Backplane
2 for Control Net/Ethernet, DH+ Channel A, or DH+ Channel B
3 for Serial

s is the slot number where the PLC is installed, such as 0, 1, 2.

Optional - "1,0"

string

String with the format "p,s"

settings
.propertyMapList
.tagType

specifies the binary format of the PLC data represented by the tag.

Required - No default value

string

"bit"
"int8"
"uint8"
"int16"
"uint16"
"int32"
"uint32"
"int64"
"uint64"
"float32"
"float64"
"byte"
"string"


params.settings.plcType property values

Value

Note

controllogix

The tag is in a Control Logix-class PLC. Includes Logix, CompactLogix, Contrologix.

plc5

The tag is in a PLC/5 PLC.

slc500

The tag is in a SLC 500 PLC.

logixpccc

The tag is in a Control Logix-class PLC using the PLC/5 protocol.

micro800

The tag is in a Micro800-class PLC.

micrologix

The tag is in a Micrologix PLC.

omron-njnx

The tag is in an Omron NJ/NX PLC.