Creating a Modbus TCP Device

After creating a device 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.

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)

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

Display only: doesn't change communication

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).

Max Registers Per Read

The largest contiguous block of registers Koios will request in a single read.

Default: 125
Range: 1–125

The Modbus specification caps a single read at 125 registers, but many devices accept fewer. Gateways that bridge to serial devices are the common case, since the serial side re-imposes its own frame limit. Published limits of 8, 16, 32, and 64 registers are all common.

Lower this when reads fail even though each register is individually valid — for example, every tag on the device reporting a read failure while the same registers read correctly one at a time in the register browser. Lowering it splits one oversized request into several smaller ones; the values you get back are unchanged.

Lower it only as far as the device needs

Each reduction increases the number of requests per scan. A device with 100 contiguous registers needs one request at 125 but 25 requests at 4, which lengthens every scan cycle. Start from the limit in the device's documentation rather than guessing low.

After Configuration

Once you've filled in the connection settings:

Save the configuration
Test the connection: click the
Test
button to verify Koios can reach the device
Add tags: define the registers you want to read or write (see Creating a Modbus TCP Tag)
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

Creating an OPC-UA Device Creating an EtherNet/IP Device