Skip to main content

Tutorials

Modbus tutorials

Requirements:

Complete the tutorial requirements before this procedure.

  1. Ensure that the Modbus service is enabled in the FairCom Edge server.

    1. Navigate to and open the services.json file in the config folder.

    2. Ensure the "enabled" property is set to true.

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

  2. Launch the open-source Modbus simulator that is included with the package to change the simulated data.

    1. Open a command prompt.

    2. Navigate to the simulator in <FairCom Folder>/server/modbus/test/<OS folder>/diagslave.<#.##>/<OS version folder>/.

    3. Run the following command at the command prompt to start the Modbus simulator that will answer Modbus requests.

      diagslave -m tcp -p 1505

    4. Connect to the "diagslave" and set the defined Modbus data item.

      1. Open another command prompt.

      2. Navigate to <FairCom Folder>/server/modbus/test/<OS folder>/modpoll-<#.##>/<OS version folder>/.

      3. Run modpoll to create data.

        Note

        You can run it multiple times with different parameters to change the Modbus data.

        • modpoll -m tcp -p 1505 -a 5 -r 1200 -c 1 localhost 65

        • modpoll -m tcp -p 1505 -a 5 -r 1200 -t 0 -c 1 localhost 1

        • modpoll -m tcp -p 1505 -a 5 -r 1300 -c 2 localhost 0x47F1 0x2000

Note

The Modbus simulator will answer the Modbus TCP requests with the following data items:

  • "temperature"

    Temperature is a register containing an integer number.

  • "volume"

    Volume is a register containing a floating point number.

  • "status"

    Status is a coil containing a Boolean.

Complete the tutorial requirements before this procedure.

  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".

This procedure creates an input named "modbusTCP" that takes Modbus TCP data and stores it in JSON format in the payload field of records in a table named "modbusTableTCP" 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:

    {
      "authToken": "ReplaceWithValidToken",
      "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
            }
          ]
        },
        "schemaName": "admin",
        "tableName": "modbusTableTCP",
        "databaseName": "ctreeSQL",
        "retentionPolicy": "autoPurge",
        "retentionPeriod": 30,
        "retentionUnit": "day",
        "metadata": {
        }
      }
    }
  4. Click Apply defaults to JSON request (Apply.PNG) 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 completed successfully.

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure, see Errors and contact FairCom with any questions.

  1. Start the FairCom Data Explorer.

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

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

    Note

    The table records are displayed as one record per row.

  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.

This procedure creates a transform named "transform_modbus1" that will transform the JSON-based data from the "modbusTableTCP" table into fields in a new table called "modbus1" in the FairCom database.

  1. Select Hub 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:

    {
      "authToken": "ReplaceWithValidToken",
      "api":"hub",
      "action":"createTransform",
      "params":
      {
        "transformName":"transform_modbus1",
        "transformActions":[
          {
            "inputFields":["source_payload"],
            "transformActionName":"jsonToDifferentTableFields",
            "outputFields":[
              "temperature",
              "volume",
              "status"
            ],
            "transformParams":
            {
              "targetTableName":"modbus1",
              "mapOfPropertiesToFields":[
                {
                  "propertyPath":"temperature",
                  "name":"temperature",
                  "type":"integer"
                },
                {
                  "propertyPath":"volume",
                  "name":"volume",
                  "type":"double"
                },
                {
                  "propertyPath": "status",
                  "name": "status",
                  "type": "bit"
                }
              ]
            }
          }
        ]
      }
    }
    
  4. Click Send request (Runbutton.png).

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

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure, see Errors and contact FairCom with any questions.

Once the transform has been created, alter the input so that data added to the "modbusTableTCP" table will also be stored in rows in the "modbus1" 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:

    {
       "authToken": "",
       "api": "hub",
       "action": "alterInput",
       "params": {
           "inputName": "modbusTCP",
           "transformName": "transform_modbus1"
       }
    }
    
  4. Click Send request (Runbutton.png).

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

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure, see Errors and contact FairCom with any questions.

View the "modbus1" 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 modbus1 table in the Server navigation window through ctreeSQL>admin>Tables>.

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

  5. Observe the table records.

    Note

    The table records are displayed as one record per row.

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 modbus1 where temperature > 60;
  3. Click the Execute SQL statement button (Runbutton.png).

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

Once Modus TCP 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:

    {
      "authToken": "ReplaceWithValidToken",
      "api": "mq",
      "action": "configureTopic",
      "params":
      {
        "topic": "modbusForward",
        "databaseName": "faircom",
        "tableName": "modbusTableTCP"
      }
    }
    
  4. Click Send request (Runbutton.png).

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

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure, see Errors and contact FairCom with any questions.

  1. Start the FairCom Browser-Based tools.

  2. Select and connect to MQ Explorer.

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

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

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

  6. Click + Subscribe (+Subscribe).

  7. Close the Manage Subscriptions window.

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

  9. Click Subscribe (Subscribe).

  10. Delete your subscription from the list.

  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",
      "authToken": "ReplaceWithValidToken",
      "action": "getRecordsByIndex",
      "params": {
        "databaseName": "faircom",
        "tableName": "modbus1",
        "indexName": "ts_index"
      }
    }
  4. Click Send request (Runbutton.png).

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

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure, see Errors and contact FairCom with any questions.