Reading Modbus Data with ControlCom Edge Server

A Modbus client tells the Edge Server which Modbus device to poll, which registers or coils to read, and which platform variable each value lands in. You configure it from the platform in the device's SDK Configuration editor; the Edge Server picks the configuration up on its next restart.

Prerequisites

The Edge Server must already be onboarded as a ControlCom Gateway. The Edge Server getting started guide covers deployment and onboarding.

Each register you read needs a variable on the gateway to receive it. Create those first (see Creating a Variable); you select each variable by its Topic Property Path when you add a tag below. The tag editor also has a Create New Variable button if you prefer to create them as you go.

Creating a Modbus Client

1. Open Devices under System in the sidebar and select the onboarded gateway.
2. Open the Edge Server tab. The SDK Configuration editor opens on its Clients tab.
3. Click Add Client and choose Modbus TCP or Modbus RTU in the Add New Client dialog. This guide uses Modbus TCP.

The new client opens in a side panel and also appears as a card on the Clients tab; click the card to reopen it later. New clients start disabled.

Modbus RTU talks to the device over a serial port, so the Edge Server container needs a volume mount for that serial device. This guide does not cover that setup.

The client panel has four tabs: Connection, Units, Settings and Tags.

Connection

1. Enter a Modbus Client Name.
2. Enter the Endpoint IP of the Modbus device on the local network, such as 192.168.1.1. For Modbus RTU this field is Device Path instead (the serial device path), with Baudrate, Data Bits, Stop Bits and Parity below it.
3. Enter the Endpoint Port. Modbus TCP uses 502.
4. Leave Client Concurrency at 1, Round size at 36, Interval at 1000 and Timeout (seconds) at 15 unless the device needs otherwise.
5. Turn on Zero Based if the device numbers its registers from 0 rather than 1.
6. Turn on Enabled.

Client Concurrency is how many Modbus requests may be in flight at once. Round size is the maximum number of consecutive registers read in a single request. Interval is the polling period in milliseconds. Timeout is how many seconds to wait for a response before the request is treated as failed.

Units

A unit is one Modbus slave behind the endpoint. Click Add New Modbus Unit and enter its Unit ID (the first unit defaults to 1, and each new one takes the next number). Two toggles control how multi-register values are decoded: bigEndian (on by default) sets the byte order, and swapWords (off by default) reverses the register order for 32-bit and larger data types.

Example: 32-bit float value 0x12345678

Normal order: Register 1 = 0x1234, Register 2 = 0x5678
Swapped words: Register 1 = 0x5678, Register 2 = 0x1234

Settings

The Settings tab holds maintenance actions: Remove Client deletes the client from this configuration, Export Variables downloads the tag list as a CSV for bulk editing, and Import Client Variables loads a tag list from a CSV.

Tags

A tag is one value read from the device. Click Add Item, then select the new entry in the list on the left. Sort Items by Address keeps the list in address order.

On the General tab:

1. Enter the Unit Id of the unit that holds the value (defaults to 1).
2. Select the Address Scope: Coils (0x01) - PhysicalState, Discrete Inputs (0x02) - InternalState, Input Registers (0x04) - PhysicalRegister or Holding Registers (0x03) - InternalRegister. Holding Registers is the default.
3. Select the Topic Property Path, which is the variable that receives the value.
4. Optionally select a Write Command to let the platform write to this register when a matching command is sent. The default is No Write Allowed.
5. Select the Data Type: Bit, Int16, UInt16, Int32, UInt32, Float, Double64, Int64 or UInt64. Choosing Bit adds a Bit field for the bit position within the register.
6. Enter the Address of the register. This is the offset within the scope, not the full Modbus address: for a holding register at 400001, the address is 1.

On the Scaling tab, Scale (defaults to 1) multiplies the raw value, Offset (defaults to 0) is added after scaling, and Decimals (defaults to 2) rounds the result. If the device reports 857 and the real value is 8.57, set Scale to 0.01.

On the Misc tab, Send if Stale After Milliseconds forces a publish when the value has not changed in that time (defaults to 600000, ten minutes, with presets for 10m, 1h, 6h and 1d), and Deadband Percentage (defaults to 5) suppresses changes smaller than that share of the previous value. Byte Order and Swap Words override the unit's endianness settings for this tag alone.

On the Transforms tab you can add Value Transforms that rewrite the value before it is published.

Saving

Click Save Configuration in the editor header, then confirm with Save Configuration in the Save SDK configuration? dialog. The configuration is stored on the platform; the gateway applies it on its next restart.

Deployment

The Edge Server reads its configuration when it starts, so a restart is what puts the new client into service. There are two ways to trigger one.

From the platform, open the gateway's Details tab and click Restart in the Send command panel. The Edge Server restarts and reconnects with the new configuration. Edge Server Management describes the full set of SDK commands.

On the gateway itself, restart the container as described in the Edge Server getting started guide.