Configure data source

Save PDF

Last UpdatedApr 22, 2025
4 minute read

To use the adapter, you must configure the data source from which it polls data. For devices on a poorly behaving network it is best to isolate the device into a separate component.

Configure Modbus TCP data source

Complete the following steps to configure a Modbus TCP data source. Use the PUT method in conjunction with the api/v1/configuration/<ComponentId>/DataSource REST endpoint to initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for a Modbus TCP data source into the file.

For sample JSON, see example below.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see see example below.

4. Save the file. For example, as ConfigureDataSource.json.

5. Open a command line session. Change directory to the location of ConfigureDataSource.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the data source configuration.

curl -d "@ConfigureDataSource.json" -H "Content-Type: application/json" -X PUT "http://localhost:5590/api/v1/configuration/Modbus1/DataSource"

Alternatively, use the following edgecmd command:

edgecmd -cid Modbus1 set datasource -file ./ConfigureDataSource.json

Notes:

If you installed the adapter to listen on a non-default port, update 5590 to the port number in use.

If you use a component ID other than Modbus1, update the endpoint with your chosen component ID.

For a list of other REST operations you can perform, like updating or deleting a data source configuration, see example below.

7. Configure data selection.

For more information, see example below.

Modbus TCP data source schema

The full schema definition for the Modbus data source configuration is in the Modbus_DataSource_schema.json file located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\Modbus\Schemas

Linux: /opt/OSIsoft/Adapters/Modbus/Schemas

Modbus TCP data source parameters

The following parameters are available for configuring a Modbus TCP data source.

Parameter	Required	Type	Description
Devices	Required	Array of objects	List of Modbus devices that this adapter instance reads. All devices read by the adapter share the common configuration defined in this table. For the properties that a device is comprised of, see the Devices table below.
StreamIdPrefix	Optional	string	Specifies what prefix is used for Stream IDs. The naming convention is {StreamIdPrefix}{StreamId}. An empty string means no prefix will be added to the Stream IDs and names. A null value defaults to ComponentID followed by a period. Example: Modbus1.{DeviceId}.{UnitId}.{RegisterType}.{RegisterOffset} Note: Every time you change the StreamIdPrefix of a configured adapter, for example when you delete and add a data source, you need to restart the adapter for the changes to take place. New streams are created on adapter restart and pre-existing streams are no longer updated. Allowed value: any string Default value: null
DefaultStreamIdPattern	Optional	string	Specifies the default stream Id pattern to use. Allowed value: any string Default value: {DeviceId}.{UnitId}.{RegisterType}.{RegisterOffset}.
ReconnectInterval	Optional	string	Parameter to specify the TimeSpan to wait before trying to reconnect to the data source when the data source is offline. * Minimum value: 00:00:00.1 Maximum value: 00:00:30 Default value: 00:00:01
RequestTimeout	Optional	string	Parameter to specify the TimeSpan that the adapter waits for a pending request before marking it as timed out and dropping the request. * Minimum value: must be positive Maximum value: 48 hours or 02:00:00:00 Default value: 00:00:10
DelayBetweenRequests	Optional	string	Parameter to specify the minimum TimeSpan between two successive requests sent to the data source. * Minimum value: 00:00:00 Maximum value: 00:00:01 Default value: 00:00:00
MaxResponseDataLength	Optional	number	Parameter to limit the maximum length (in bytes) of data that can be read within one transaction. This feature is provided to support devices that limit the number of bytes that can be returned. If there is no device limitation, the request length should be the maximum length of 250 bytes. Minimum value: 2 Maximum value: 250 Default value: 250

* Note: You can also specify timespans as numbers in seconds. For example, "RequestTimeout": 25 specifies 25 seconds, or "RequestTimeout": 125.5 specifies 2 minutes and 5.5 seconds.

Devices

The following parameters are available for configuring the 'Devices' parameter of a Modbus TCP data source.

Parameter	Required	Type	Description
Id	Required	string	The ID of the device that is used in data selection to associate a register with a device.
IpAddress	Required	string	The IP address or hostname of the device from which the data is collected using the Modbus TCP protocol.
Port	Optional	number	The TCP port of the target device that listens for and responds to Modbus TCP requests. The value ranges from 0 to 65535. If you do not configure it, the default TCP port is 502, which is the default port for Modbus TCP protocol.

Modbus TCP data source examples

The following are examples of valid Modbus TCP data source configurations:

Minimal data source configuration

{

"Devices":

[

{

"id": "Device1",

"ipAddress": "127.0.0.1"

}

]

}

Complete data source configuration

{

"Devices":

[

{

"id": "Device1",

"ipAddress": "127.0.0.1",

"port": 502

{

"id": "Device2",

"ipAddress": "127.0.0.2",

"port": 502

{

"id": "Device3",

"ipAddress": "127.0.0.3",

"port": 502

}

"streamIdPrefix": "my.prefix",

"defaultStreamIdPattern": "{DeviceId}.{UnitId}.{RegisterType}.{RegisterOffset}",

"reconnectInterval": "00:00:01",

"requestTimeout": "00:00:10",

"delayBetweenRequests": "00:00:00.5",

"maxResponseDataLength": 125

}

REST URLs

Relative URL	HTTP verb	Action
api/v1/configuration/<ComponentId>/DataSource	GET	Retrieves the data source configuration.
api/v1/configuration/<ComponentId>/DataSource	POST	Creates the data source configuration. The adapter starts collecting data after the following conditions are met: - The data source configuration POST request is received. - A data selection configuration is active.
api/v1/configuration/<ComponentId>/DataSource	PUT	Configures or updates the data source configuration. Overwrites any active data source configuration. If no configuration is active, the adapter starts collecting data after the following conditions are met: - The data source configuration PUT request is received. - A data selection configuration is active.
api/v1/configuration/<ComponentId>/DataSource	DELETE	Deletes the data source configuration. After the request is received, the adapter stops collecting data.

Note: Replace <ComponentId> with the Id of your Modbus TCP component. For example, Modbus1.

AVEVA™ Adapter for Modbus TCP