This quickstart tutorial walks through how to capture, store, transform, forward, and query data using the Modbus simulator.
Requirements
- Ensure the FairCom server is installed and running.
- Verify that the Modbus service is enabled in the FairCom Edge server.
- Edit the
services.jsonfile in theconfigfolder. - Locate the
"integrationServices"object of the service for the desired platform. - Set
"enabled"totrue.-
Windows
"integrationServices": [ { "serviceName": "modbus", "serviceLibrary": "modbusservice.dll", "schemaName": "modbus", "enabled": true }, -
Unix/Linux
"integrationServices": [ { "serviceName": "modbus", "serviceLibrary": "libmodbusservice.so", "schemaName": "modbus", "enabled": true }, -
MAC
"integrationServices": { "serviceName": "modbus", "serviceLibrary": "modbusservice.dylib", "schemaName": "modbus", "enabled": true }
-
Windows
- Save any changes. Restart FairCom Edge Server.
- Confirm server access by running the FairCom Control Center. The typical URL is https://localhost:8443/.
Initialize the Modbus simulator
Launch the open-source Modbus simulator that is included with the package to change the simulated data.
- Open a command prompt.
- Navigate to the simulator in <FairCom Folder>/server/modbus/test/<OS folder>/diagslave.<#.##>/<OS version folder>/.
- Run the following script at the command prompt to start the Modbus simulator that will answer Modbus TCP requests.
diagslaveTCP.sh (or diagslaveTCP.bat on Windows)
- Connect to the
"diagslave"and set the defined Modbus data item.- Open another command prompt.
- Navigate to <FairCom Folder>/server/modbus/test/<OS folder>/modpoll-<#.##>/<OS version folder>/.
- Run the following script to write some data.
modpollTCP.sh (or modpollTCP.bat on Windows)
- 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.
-
Create a session
- Start the FairCom Control Center.
- Sign in with the username and password. FairCom's default username is ADMIN (case-insensitive) and the password is ADMIN (case-sensitive).
Note When you log into the FairCom Control Center, a session is automatically created. Any request submitted in the API Console will have the "authToken" property automatically populated with that session's auth token. If you aren't following this tutorial inside the FairCom Control Center, you must first execute the createSession action and set the "authToken" property manually.
Create an Integration Table for Modbus TCP data
This procedure creates an Integration Table named modbustabletcpin the faircom database to store data received from a Modbus TCP source. The Integration Table automatically creates the create_ts, error, and source_payload JSON fields.
- Navigate to the Code tab from the sidebar menu and select API Console.
- Copy and paste the following code into the API Console request:
{ "action": "createIntegrationTable", "params": { "databaseName": "faircom", "ownerName": "admin", "tableName": "modbustabletcp" }, "authToken": "replaceWithAuthTokenFromCreateSession" }
- Click the Run button.
- Observe the response in the Output section and ensure the action is completed successfully.
Note
"errorCode"with a value of0indicates success."errorCode"with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.
Create Tags to this Integration Table
This procedure creates two tags. They represent properties in table modbustabletcp, field source_payload. The tags are also assigned to user-defined fields (temperature and volume) and its values are automatically synchronized with the source_payload properties.
- Copy and paste the following code into the API Console request:
{ "action": "createTag", "params": { "tagName": "temperature", "tableName": "modbustabletcp", "tagDataType": "number", "sourcePayloadPath": "temperature", "sourceFieldName": "temperature", "sourceFieldType": "float", "sourceFieldLength": 8 }, "authToken": "replaceWithAuthTokenFromCreateSession" }
- Click the Run button.
- Observe the response in the Output section and ensure the action is completed successfully.
- Do the same to create the second tag:
{ "action": "createTag", "params": { "tagName": "volume", "tableName": "modbustabletcp", "tagDataType": "number", "sourcePayloadPath": "volume", "sourceFieldName": "volume", "sourceFieldType": "integer", "sourceFieldLength": 8 }, "authToken": "replaceWithAuthTokenFromCreateSession" }
Capture Modbus TCP data in the Integration Table
This procedure creates an input that captures data from an Modbus TCP source and writes the incoming data to the modbustabletcp Integration Table for subsequent processing.
- Copy and paste the following code into the API Console request:
{ "action": "createInput", "params": { "inputName": "modbusTCP", "serviceName": "modbus", "dataCollectionIntervalMilliseconds": 5000, "settings": { "modbusProtocol": "TCP", "modbusServer": "127.0.0.1", "modbusServerPort": 502, "modbusDataAddressType": "oneBased", "propertyMapList": [ { "tagName": "temperature", "modbusDataAddress": 1200, "modbusDataAccess": "inputRegister", "modbusUnitId": 5, "modbusDataLen": 1 }, { "tagName": "volume", "modbusDataAddress": 1300, "modbusDataAccess": "inputRegister", "modbusUnitId": 5, "modbusDataLen": 2 } ] }, "schemaName": "admin", "tableName": "modbustabletcp", "databaseName": "faircom" }, "authToken": "replaceWithAuthTokenFromCreateSession" }
- Click the Run button.
- Observe the response in the Output section and ensure the action is completed successfully.
Note
"errorCode"with a value of0indicates success."errorCode"with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.
That is all that is required to configure the FairCom server to read data from a device via the Modbus protocol. Continue the tutorial to learn how to view the collected data, forward the collect data to a MQTT topic and how to write data to a Modbus device.
View the transformed data
View the modbustabletcp table in the faircom database for the transformed data.
All of the following procedures will let you view the transformed data. You can use either of these procedures to view the transformed data.
View collected data through the Integration Tables navigation window
- Navigate to the Data tab from the sidebar menu and select Integration Tables.
- Click on the
modbustabletcptable. - Click on the fields section.
- Search for and enable the
temperatureandvolumefields. Optionally, you can click at Hide system fields to show only the user fields.

- For each piece of data collected, it is possible to see its values and information. For example, in the last record collected the temperature is
65.

View collected data executing a SQL query
- Navigate to the Data tab from the sidebar menu and select SQL Commands.
- In the Statement section, enter and run the following SQL query:
select create_ts, temperature from modbustabletcp where temperature > 60;
- Observe the response and ensure the action is completed successfully.
Query captured Modbus TCP data using the JSON API
- Navigate to the Code tab from the sidebar menu and select API Console.
- Copy and paste the following code into the API Console request to get data from
modbustabletcpusing the timestamp order (ts_index):{ "action": "getRecordsByIndex", "params": { "databaseName": "faircom", "tableName": "modbustabletcp", "indexName": "ts_index" }, "authToken": "replaceWithAuthTokenFromCreateSession" }
- Click the Run button.
- Observe the response in the Output section and ensure the action is completed successfully.
Forward captured data to an MQTT topic
Once Modbus TCP data is flowing into a table as JSON and is being transformed into discrete fields in the same table, forward the data out over MQTT.
- Navigate to the Code tab from the sidebar menu and select API Console.
- Copy and paste the following code into the API Console request:
{ "action": "configureTopic", "params": { "topic": "modbusForward", "databaseName": "faircom", "tableName": "modbustabletcp" }, "authToken": "replaceWithAuthTokenFromCreateSession" }
- Click the Run button.
- Observe the response in the Output section and ensure the action is completed successfully.
- Subscribe to the MQTT topic to verify that your data was forwarded.
- Navigate to the MQ tab from the sidebar menu and select Messages.
- Click the Add Subscription button. In the Topic filter search bar, select
"modbusForward"and click Subscribe. As soon as new data is read, messages will appear in the Messages section.

Configure Modbus to output data to a device
The following example configures a Modbus connector to output data to a Modbus device. When MQTT, SQL, JSON DB, or an input connector inserts a record into the "modbustabletcp" integration table, the FairCom server delivers the record to the Modbus connector. This example configures the Modbus connector to extract the value of the temperature property from the record’s source_payload field and write it to a device (address 1500) using the Modbus protocol.
- Navigate to the Code tab from the sidebar menu and select API Console.
- Copy and paste the following code into the API Console request:
{ "action": "createOutput", "params": { "outputName": "writeTemperatureToModbus", "serviceName": "modbus", "databaseName": "faircom", "ownerName": "admin", "tableName": "modbustabletcp", "settings": { "modbusProtocol": "TCP", "modbusServer": "127.0.0.1", "modbusServerPort": 502, "modbusDataAddressType": "oneBased", "propertyMapList": [ { "propertyPath": "temperature", "modbusDataAddress": 1500, "modbusDataAccess": "holdingregister", "modbusUnitId": 5, "modbusDataLen": 1 } ] } }, "authToken": "replaceWithAuthTokenFromCreateSession" }
- Click the Run button.
- Observe the response in the Output section and ensure the action is completed successfully.
- In the diagslave output there will be write operations to address 1500.
Slave 5: readInputRegisters from 1200, 1 references Slave 5: readInputRegisters from 1300, 2 references Slave 5: readCoils from 1200, 1 references Slave 5: writeHoldingRegisters from 1500, 1 references Slave 5: readInputRegisters from 1200, 1 references Slave 5: readInputRegisters from 1300, 2 references Slave 5: readCoils from 1200, 1 references Slave 5: writeHoldingRegisters from 1500, 1 references
