Creating a Device

To create a device, navigate to the Devices page and click the

+ Add Device

button in the top-right corner. This opens a form where you configure the basic properties of the device.

Protocol-specific configuration comes later

The create form only captures the essentials — name, protocol, and scan rate. Protocol-specific settings (endpoints, credentials, timeouts) are configured on the device's Configuration tab after creation.

Form Fields

Name

A unique, human-readable identifier for the device. This is how you'll find and reference the device throughout the platform.

Required
Must be unique across all devices
Examples: Chiller-01, AHU North Wing, Warehouse PLC

Description

An optional free-text field for notes about the device — its location, purpose, or any context that helps your team identify it.

Protocol

The communication protocol Koios will use to connect to this device. Select from the available protocols in the dropdown. See Protocols for a full description of each protocol and when to use it.

Protocol cannot be changed after creation

The protocol is locked once the device is created. If you need to change it, you'll need to create a new device with the correct protocol and recreate the tags.

Scan Rate (seconds)

How often Koios reads from and writes to the device. The default is 1 second.

Required
Minimum: 0.1 seconds (100ms)
Step: 0.1 seconds
Typical ranges:
- 0.1–1s for fast-changing process data (temperatures, pressures)
- 5–30s for slower-moving data (energy meters, environmental sensors)
- 60–300s for infrequently changing data (database queries, batch systems)

Start conservative

A faster scan rate means more network traffic and CPU usage. Start with a moderate rate (e.g. 5 seconds) and decrease it only if your application needs faster data.

Heartbeat Scans

The number of scan cycles between heartbeat toggles. The default is 10 scans.

The heartbeat is a counter that toggles on a regular interval, allowing external systems (like a BMS or SCADA) to verify that Koios is actively scanning. If the heartbeat stops toggling, the external system knows something is wrong.

Required
Minimum: 1 scan
With the default scan rate of 1 second and heartbeat scans of 10, the heartbeat toggles every 10 seconds

After Creation

Once you click Create Device, Koios creates the device and navigates you to its Configuration tab. From here you'll need to:

Configure protocol settings — provide the connection details for your protocol (endpoint URL, hostname, credentials, etc.). See the protocol-specific guides:
Test the connection — use the Test Connection button on the Configuration tab to verify Koios can reach the device before enabling it
Add tags — create the data points you want to read from or write to the device (see Creating a Tag)
Enable the device — flip the enable switch in the device header to start scanning

Duplicating a Device

If you need to create a device similar to an existing one, you can duplicate it instead of starting from scratch. Right-click a device in the list and select Duplicate, or use the duplicate action on a device's detail page.

Duplicating copies:

All protocol-specific configuration (endpoints, credentials, timeouts)
Scan rate and heartbeat settings
Advanced settings (on-demand scanning, log level)

It does not copy:

Tags — you'll need to add tags to the new device separately
The enabled state — the duplicate is always created disabled

You'll be prompted to enter a new name and optionally update the description before confirming.

Device Introduction Creating an OPC-UA Device