Creating a Device
To create a device, navigate to the Devices page and click the
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.
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)
Heartbeat Scans
The number of scan cycles between heartbeat toggles. The create form pre-fills 10 scans (the stored default when omitted on import is 1 scan).
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
On-Demand Freshness
The maximum age of cached tag data before an on-demand request triggers a fresh read from the device. Lower values give fresher data at the cost of more device I/O.
- Default: 1 second
- Range: 0–3,600 seconds (0 means always scan)
On-Demand Batch Window
How long Koios waits for further on-demand requests before executing a single batched read, so concurrent requests for the same device share one round trip.
- Default: 0.1 seconds
- Range: 0–10 seconds (0 means no batching)
See On-Demand Scanning for how these two settings affect model inference latency.
After Creation
Once you click Create Device, Koios creates the device and navigates you to its Configuration tab. From here you'll need to:
Review the protocol settings: check the connection details you entered on the middle step of the Add Device form (endpoint URL, hostname, credentials, etc.) and fill in anything you skipped. See the protocol-specific guides:
Test the connection: use the Test button on the Configuration tab to verify Koios can reach the device before enabling it. (Microsoft SQL devices have no Test button — enable the device and check its Overview tab for the first connection result.)
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
- The on-demand freshness and batch window settings
- The folder the original device sits in
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
- The log level: it is a runtime override held in the live data cache rather than saved device configuration, so the duplicate starts at the default level
You'll be prompted to enter a new name and optionally update the description before confirming.