--- title: Reading Modbus with Edge Server description: Configure a Modbus TCP or Modbus RTU client on the ControlCom Edge Server to poll registers and coils into platform variables. source: https://documentation.controlcomtech.com/build/edge-server/clients/modbus --- # 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. > **Workflow Stage: Collect** ## Prerequisites The Edge Server must already be onboarded as a ControlCom Gateway. The [Edge Server getting started guide](https://documentation.controlcomtech.com/build/edge-server/getting-started) covers deployment and onboarding. Each register you read needs a variable on the gateway to receive it. Create those first (see [Creating a Variable](https://documentation.controlcomtech.com/build/edge-server/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. ![Edge Server Clients tab](https://documentation.controlcomtech.com/images/devices/edge-server-clients-screen.png) *Edge Server tab with no clients yet. Click Add Client to begin* ![Add New Client dialog](https://documentation.controlcomtech.com/images/devices/edge-server-add-client-screen.png) *Add New Client dialog with Modbus TCP, Modbus RTU, OPC UA, BACnet, and Ethernet/IP options* 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. ![Devices Edge Server Page Modbus Connections tab](https://documentation.controlcomtech.com/images/devices/modbus-client-connection.png) *The Connection tab of a Modbus client* ### 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 ``` ![Devices Edge Server Page Modbus Units tab](https://documentation.controlcomtech.com/images/devices/modbus-client-units.png) *The Units tab of a Modbus client* ### 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](https://documentation.controlcomtech.com/build/edge-server/data-processors#value-transforms) that rewrite the value before it is published. ![Devices Edge Server Page Modbus Tags tab](https://documentation.controlcomtech.com/images/devices/modbus-client-tags.png) *The Tags tab of a Modbus client* ## 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](https://documentation.controlcomtech.com/platform/devices/edge-server#sdk-commands) describes the full set of SDK commands. On the gateway itself, restart the container as described in the [Edge Server getting started guide](https://documentation.controlcomtech.com/build/edge-server/getting-started). ![Restarting Device](https://documentation.controlcomtech.com/images/devices/device-details-page.png) *The Details tab, with the Send command panel used to restart the Edge Server*