---
title: "Creating a Modbus TCP Device"
description: "Configure a connection to a Modbus TCP device"
source_url: https://ai-ops.com/docs/devices/creating-modbus-tcp
---

# Creating a Modbus TCP Device

After [creating a device](https://ai-ops.com/docs/devices/creating-getting-started.md) with the **Modbus TCP** protocol, you'll land on its **Configuration** tab. This is where you provide the connection details Koios needs to communicate with your Modbus device.

> [!NOTE] Register-based protocol
> Modbus TCP uses a register-based addressing model. Each data point is identified by a register type (Coil, Discrete Input, Input Register, or Holding Register) and an address number. You'll configure these at the tag level — the device configuration only handles the connection itself.

## Configuration Fields

### Hostname

The IP address or hostname of the Modbus TCP device.

- **Required**
- Example: `192.168.1.100`

### Port

The TCP port the Modbus device is listening on.

- **Default:** 502 (the standard Modbus TCP port)

> [!TIP] Non-standard ports
> Most Modbus devices use port 502. Some devices (especially gateways or simulators) may use a different port — check the device documentation if you're having trouble connecting.

### Unit ID

The Modbus unit identifier (also called slave address). This identifies which device on the network to communicate with.

- **Default:** 1
- **Range:** 0–255

For a single device connected directly over Ethernet, the Unit ID is typically **1**. When connecting through a Modbus gateway that bridges to serial devices, the Unit ID identifies which downstream device to address.

### Timeout

How long Koios waits for the device to respond before giving up, in seconds.

- **Default:** 5 seconds
- Specified in **seconds**

For local network connections, a timeout of 1–3 seconds is usually sufficient. Increase it for devices behind gateways or on slow links.

### Show One-Based Addresses

Controls how register addresses are displayed in the UI.

- **Default:** Off (0-based addressing)
- When **enabled**, register addresses are displayed starting from 1 instead of 0

> [!NOTE] Display only — doesn
> This setting only affects how addresses appear in the Koios UI. The underlying Modbus communication always uses 0-based addressing per the protocol specification. Enable this if your device documentation uses 1-based register maps (common with some manufacturers).

## After Configuration

Once you've filled in the connection settings:

1. **Save** the configuration
2. **Test the connection** — click the `Test` button to verify Koios can reach the device
3. **Add tags** — define the registers you want to read or write (see [Creating a Modbus TCP Tag](https://ai-ops.com/docs/tags/creating-modbus-tcp.md))
4. **Enable the device** — flip the enable switch to start scanning

## Register Scanning

Koios provides tools to scan and interpret Modbus registers directly from the device, which is useful for discovering available data points and verifying correct byte/word order before creating tags.

### Scan Registers

You can scan a range of registers to see their raw values. Specify:
- **Register type** — Coil, Discrete Input, Input Register, or Holding Register
- **Start address** — the first register to read
- **Count** — how many consecutive registers to read

### Interpret Registers

After scanning, you can interpret raw register values using different data types to find the correct interpretation. This helps you determine:
- The correct **data type** (Int16, UInt16, Float32, etc.)
- Whether **byte swap** or **word swap** is needed
- The **bit position** for Boolean values within a register