Initialize the Modbus simulator

Launch the open-source Modbus simulator that is included with the package and open a prompt to change temperature values.

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.
   1. diagslave -m tcp -p 502
4. Prepare to change Modbus data (temperature).
   1. Open another command prompt.
   2. Navigate to <FairCom Folder>/server/modbus/test/<OS folder>/modpoll-<#.##>/<OS version folder>/.

Create a session

1. Start the FairCom browser-based tools.
   1. The tools icons appear.
2. Select and log in to Data Explorer.
   1. The Data Explorer interface window appears.
3. Click the API Explorer tab.
   1. The API Explorer interface opens, and the Server navigation window shows that you are connected to the FairCom database and the FairCom server.

Capture Modbus TCP data as JSON records in a table

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.

Not all data will be persisted. There are some conditional settings that define when to persist data and which data to persist.

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

   1. {
       "api": "hub",
       "action": "createInput",
       "params": {
         "inputName": "modbusTCP",
         "serviceName": "modbus",
         "tableName": "modbusTableTCP",
         "databaseName": "faircom",
         "dataCollectionIntervalMilliseconds": 2000,
         "dataPersistenceStrategy": "onChange",
         "immediatelyCollectDataOnStart": false,
         "onChangeTrigger": "saveWhenAnySpecifiedTagHasChanged",
         "onChangeTriggerTags": ["temperature","volume"],
         "onChangeScope": "saveOnlyChangedTags",
         "maxUnsavedEvents": 30,
         "settings": {
           "modbusProtocol": "TCP",
           "modbusServer": "127.0.0.1",
           "modbusServerPort": 502,
           "modbusDataAddressType": "oneBased",
           "propertyMapList": [
             {
               "propertyPath": "temperature",
               "modbusDataAddress": 1200,
               "modbusDataAccess": "inputRegister",
               "modbusUnitId": 5,
               "modbusDataLen": 1,
               "deadbandLowerLimit": 60,
               "deadbandUpperLimit": 71,
               "normalLowerLimit": -10,
               "normalUpperLimit": 200,
               "significantMagnitude": 3
             },
             {
               "propertyPath": "volume",
               "modbusDataAddress": 1300,
               "modbusDataAccess": "holdingregister",
               "modbusUnitId": 5,
               "modbusDataLen": 2,
               "modbusDataType": "ieeefloat32ABCD"
             },
             {
               "propertyPath": "status",
               "modbusDataAddress": 1400,
               "modbusDataAccess": "coil",
               "modbusUnitId": 5,
               "modbusDataLen": 1
             }
           ]
         }
       },
       "authToken": "replaceWithAuthTokenFromCreateSession"
      }

2. Click Apply defaults to JSON request to replace the "authToken" value with the valid one from your session.
3. Click Send request to issue the JSON-based request.
   1. Observe the response and ensure the action is completed successfully.

General settings:

• Modbus data will be read every 2000 milliseconds and will be persisted if data has changed ("dataPersistenceStrategy") and if it satisfies some conditions;
• Data will be saved when any of the tags at "onChangeTriggerTags" has changed ("onChangeTrigger");
• When saving data, just include tags that changed from the last persisted data ("onChangeScope");
• After 30 skip reads, save all tags ("maxUnsavedEvents");

For "temperature" property:

• There are some conditions to define if it should be saved;
• If the value is between 60 and 71, it will not be saved. This is the deadband range ("deadbandLowerLimit" and “deadbandUpperLimit”);
• If the value is not in the deadband  range, it will just be saved if it is inside the range -10 and 200, which is called the normal range ("normalLowerLimit" and "normalUpperLimit");
• Also, changes less than 3 from the previous persisted value will be ignored as it is considered insignificant ("significantMagnitude").

View the captured Modbus TCP data in the "modbusTableTCP" table

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.
4. There will be only one record. Select it and click the source_payload field.

Change values to persist more records

Switch to the modpoll command prompt.

Some test examples:

1. Change temperature to 50

   1. modpoll -m tcp -p 502 -a 5 -r 1200 -c 1 localhost 50

   2. Go back to the table, refresh, select the last record and look at the source_payload field.
      You should see only the timestamp and temperature fields.

   3. {
       "create_ts": "2026-02-04T22:53:21.621Z",
       "temperature": 50
      }

2. Change temperature to 65

   1. modpoll -m tcp -p 502 -a 5 -r 1200 -c 1 localhost 65

   2. There should be no record as 65 is inside the deadband range.
3. Change temperature to 300

   1. modpoll -m tcp -p 502 -a 5 -r 1200 -c 1 localhost 300

   2. There should be no record as 300 is outside the normal range.
4. Change temperature to 55

   1. modpoll -m tcp -p 502 -a 5 -r 1200 -c 1 localhost 55

   2. There will be a new record at the table, as 55 pass all conditions.

   3. {
       "create_ts": "2026-02-04T22:55:37.766Z",
       "temperature": 55
      }

5. Change temperature to 56

   1. modpoll -m tcp -p 502 -a 5 -r 1200 -c 1 localhost 56

   2. There will be no record as 56 is 1 more than the last persisted value and the change is considered insignificant.
6. Change volume to 123456.0078125

   1. modpoll -m tcp -p 502 -a 5 -r 1300 -c 2 localhost 0x47F1 0x2001

   2. There will be a new record at the table as there is no conditional persistence property defined for volume. So, any change will be considered saveable.

   3. {
       "create_ts": "2026-02-04T22:56:17.778Z",
       "volume": 123456.0078125
      }

7. Wait 1 hour without changing data.
   1. There will be a new record because the maximum number of skipped records has reached ("maxUnsavedEvents"). All tags will be persisted.

   2. {
       "create_ts": "2026-02-04T23:59:59.758Z",
       "status": 0,
       "temperature": 56,
       "volume": 123456.0078125
      }