Skip to main content

Tutorials

FairCom Edge Allen-Bradley connector service tutorials

Requirements:

This page contains tutorials to set up Allen-Bradley connections through FairCom Edge

FairCom EdgeAllen-Bradleyconnectortutorials

Initialize the Allen-Bradley simulator

For this tutorial, we are using an open-source Allen-Bradley simulator available with the libplctag package.

  1. Download and extract libplctag package that is available at https://github.com/libplctag/libplctag/releases. For example, libplctag_2.6.4_windows_x64.zip.

  2. Execute Allen-Bradley Server simulator, creating some tags:

    cd \libplctag_2.6.4_windows_x64\ 

ab_server --plc=ControlLogix --path=1,0 --port=4400 --tag=MESSAGE:STRING[10] --tag=SCADA:dint[10] --tag=TEMPERATURE:real[10]

    This instruction executes the Allen-Bradley server simulator of type Control Logix, on Port 4400, creating 3 tags: SCADA, TEMPERATURE, and MESSAGE—ten tags for each.

    Leave it running.

  3. Execute tag_rw2 to write some data to the Allen-Bradley Server simulator.

    cd \libplctag_2.6.4_windows_x64\

tag_rw2 --type="sint32" --tag="protocol=ab-eip&gateway=localhost:4400&path=1,0&plc=controllogix&elem_count=10&name=SCADA" --debug=1 --write=10,20,30,40,50,60,70,80,90,100 --timeout=1000

tag_rw2 --type="real32" --tag="protocol=ab-eip&gateway=localhost:4400&path=1,0&plc=controllogix&elem_count=1&name=TEMPERATURE" --write=35.3, 1.2 --timeout=1000

tag_rw2 --type="string" --tag="protocol=ab-eip&gateway=127.0.0.1:4400&path=1,0&plc=controllogix&elem_count=5&name=MESSAGE" --debug=1 --write="check temperature","a1","a2","a3","a4" --timeout=1000

Note

There is also a Linux version of this simulator.

Create a session

  1. Start the FairCom browser-based tools.

    The tools icons appear.

  2. Select and log into Data Explorer.

    The Data Explorer interface window appears.

  3. Click the API Explorer tab.

    The API Explorer interface opens and the Server navigation window shows that you are connected to the "faircom" database and the FairCom server. Use the "faircom" database or another database you create to store the "customer tables".

Capture Allen-Bradley data as JSON records in a table

This procedure creates an input named "abTest1" that takes Allen-Bradley data and stores it in JSON format in the payload field of records in a table named "abTable1" in the "faircom" database.

  1. Select Hub API from the Select API dropdown menu.

  2. Select createInput from the JSON Actions dropdown menu.

  3. Replace the JSON in the API Request editor with the following JSON:

    {
   "api":"hub",
   "action":"createInput",
   "params":{
      "inputName":"abTest1",
      "serviceName":"ab",
      "tableName":"abTable1",
      "dataCollectionIntervalMilliseconds":5000,
      "settings":{
         "dataReadingTimeoutMilliseconds":4000,
         "dataCollectionBufferCount":1,
         "plcAddress":"localhost:4400",
         "plcType":"controllogix",
         "propertyMapList":[
            {
               "tagPath":"1,0",
               "tagName":"SCADA",
               "tagElementCount":5,
               "tagType":"int32",
               "propertyPath":"scada"
            },
            {
               "tagPath":"1,0",
               "tagName":"TEMPERATURE",
               "tagType":"float32",
               "propertyPath":"temperature"
            },
            {
               "tagPath":"1,0",
               "tagName":"MESSAGE",
               "tagType":"string",
               "tagSize":20,
               "propertyPath":"message"
            }
         ]
      }
   },
   "authToken": "replaceWithAuthTokenFromCreateSession"
}

    This request reads 5 elements from the tag "scada", and 1 element from the other tags.

  4. Click Apply defaults to JSON request (Apply) to replace the "authToken" value with the valid one from your session.

  5. Click Send request (Runbutton.png) to issue the JSON-based request.

  6. Observe the response and ensure the action is completed successfully.

Note

An "errorCode" with a value of 0 indicates success. An "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

View the captured Allen-Bradley data in the "abTest1" table

  1. Start the FairCom Data Explorer

  2. Navigate to and select abTest1 in the Server navigation window through faircom>admin>Tables.

  3. Click the Table Records tab (Table Records Tab).

  4. Select a record and click the source_payload field.

  5. Observe the JSON contents of the field. Click the "edit" icon of the source_payload field to see the content formatted as JSON.

The value should look like this:

{
  "create_ts":"2025-04-25T21:13:48.543Z",
  "scada0":10,
  "scada1":20,
  "scada2":30,
  "scada3":40,
  "scada4":50,
  "temperature":35.299999237060547,
  "message":"check temperature"
}

Note

If the table has no records, look at <faircom>/data/CTSTATUS.FCS to see errors related to the connector.

Create a transform to extract the captured data into table fields

This procedure creates a transform named "transform_ab1" that will transform the JSON-based data from the "abTest1" table into fields in a new table called "ab1" in the "faircom" database.

  1. Select the Transform API from the Select API dropdown menu.

  2. Select "createTransform" from the JSON Actions dropdown menu.

  3. Replace the JSON in the API Request editor with the following JSON:

    {
  "api":"hub",
  "action":"createTransform",
  "params":
  {
    "transformName":"transform_ab1",
    "transformActions":[
      {
        "inputFields":["source_payload"],
        "transformActionName":"jsonToDifferentTableFields",
        "outputFields":[
          "scada0",
          "scada1",
          "temperature"
        ],
        "transformParams":
        {
          "targetTableName":"ab1",
          "mapOfPropertiesToFields":[
            {
              "propertyPath":"scada0",
              "name":"scada0",
              "type":"integer"
            },
            {
              "propertyPath":"scada1",
              "name":"scada1",
              "type":"integer"
            },
            {
              "propertyPath":"temperature",
              "name":"temperature",
              "type":"double"
            }
          ]
        }
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

  4. Click Send request (Run Icon).

  5. Observe the response and ensure the action is completed successfully.

Note

An "errorCode" with a value of 0 indicates success. An "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

Attach the transform to the input

Once the transform has been created, alter the input so that data added to the "abTest1" table will also be stored in rows in the "ab1" table.

  1. Select Hub API from the Select API dropdown menu.

  2. Select alterInput from the JSON actions dropdown menu.

  3. Replace the JSON in the API Request editor with the following JSON:

    {
   "api": "hub",
   "action": "alterInput",
   "params": {
       "inputName": "abTest1",
       "transformName": "transform_ab1"
   },
   "authToken": "replaceWithAuthTokenFromCreateSession"
}

  4. Click Send request (Run Icon).

  5. Observe the response and ensure the action is completed successfully.

View the transformed data

View the "ab1" table in the "faircom" database for the transformed data.

Both of the following procedures will let you view the transformed data. You can use either of these procedures to view the transformed data.

View transformed data through the Server navigation window

  1. Select the "faircom" database in the Server navigation window.

  2. Select Connect from the JSON Actions dropdown menu.

  3. Navigate to and select the ab1 table in the Server navigation window through faircom>admin>Tables.

  4. Click the Table Records tab (Table Records Tab).

  5. Observe the table records.

View transformed data through a SQL query

  1. Click the SQL Queries tab (SQL Queries Tab).

  2. Enter the following SQL query in the textbox.

    SELECT * from ab1 where scada0>0

  3. Click the Execute SQL statement button (Run.png).

  4. Observe the response and ensure the action is completed successfully.

Forward captured data to an MQTT topic

Once Allen-Bradley data is flowing into a table as JSON and is being transformed into discrete fields in another table, forward the data out over MQTT.

  1. Select MQ API from the Select API dropdown menu.

  2. Select configureTopic from the JSON Actions dropdown menu.

  3. Replace the JSON in the API Request editor with the following JSON:

    {
  "api": "mq",
  "action": "configureTopic",
  "params":
  {
    "topic": "abTopic",
    "databaseName": "faircom",
    "tableName": "abTable1"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

  4. Click Send request (Run.png).

  5. Observe the response and ensure the action is completed successfully.

Subscribe to the MQTT topic to verify that data was forwarded

  1. Start the FairCom Browser-Based tools.

  2. Select and connect to MQ Explorer.

  3. Select MQTT Management from the Control menu (ControlMenu.png).

  4. Click Subscribe (Subscribe.png) to open the Manage Subscriptions window.

  5. Select the topic you subscribed to from the Topic dropdown menu.

  6. Click + Subscribe (SubscribePlusButton.png).

  7. Close the Manage Subscriptions window.

  8. Observe your message, displayed under Incoming Messages every 10 seconds.

  9. Click Subscribe (Subscribe.png).

  10. Delete your subscription from the list.

Query captured Allen-Bradley data using the JSON DB API

  1. Select DB API from the Select API dropdown menu.

  2. Select the getRecordsByIndex from the JSON Actions dropdown menu.

  3. Replace the JSON in the API Request editor with the following JSON:

    {
  "api": "db",
  "action": "getRecordsByIndex",
  "params": {
    "databaseName": "faircom",
    "tableName": "abTable1",
    "indexName": "ts_index"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

  4. Click Send request (Run Icon).

  5. Observe the API Response response and ensure the action is completed successfully.