Device Parameters

Every device in Koios has a set of parameters that describe its current state, configuration, and protocol-specific connection settings. You can view all parameters on a device's Parameters tab, organized into three sections: Live Data, Configuration, and Protocol.

Live Data

Live data parameters are read-only values that update in real time. They reflect the device's current operational state and are useful for monitoring and troubleshooting.

Parameter	Description
Status	The device's current connection state — Running, Stopped, or Failed
Error Code	A numeric code identifying the type of error (see Troubleshooting a Device)
Error Message	A short description of the current error, if any
Error Detail	Additional diagnostic information about the error
Heartbeat	A toggling value that increments each scan cycle — external systems can monitor this to confirm Koios is actively scanning
Missed Scans (1h)	The number of times a scan exceeded the configured scan rate in the last hour — useful for assessing current device health
Scan Progress	The percentage complete for the current scan cycle
Last Scan	The timestamp of the most recent completed scan

Mapping live data to tags

Any live data parameter can be mapped to a tag, allowing you to record its value in the time-series database or use it in expressions and models. Click the map icon next to a parameter to create a mapping.

Configuration

Configuration parameters control how the device behaves. These are set when you create or edit a device.

Core Settings

Parameter	Description	Default
Name	A unique identifier for the device	—
Description	An optional note describing the device's purpose	—
Enabled	Whether the data collector should actively scan this device	Off

Scanning

Parameter	Description	Default	Range
Scan Rate	How often Koios polls the device for new data, in seconds	1s	0.1–3,600s
On-Demand Freshness	Maximum age (seconds) of cached tag data before an on-demand request triggers a fresh device read. Lower values ensure fresher data but increase device I/O	1s	0–3,600s
On-Demand Batch Window	Time window (seconds) to batch concurrent on-demand requests into a single device read. Reduces I/O when multiple models share a device	0.1s	0–10s
Heartbeat Scans	The number of scans the heartbeat counter waits before toggling	1	—

Scan rate guidance

A scan rate of 1 second works well for most real-time monitoring. Increase it for devices on slow networks or when polling frequency isn't critical. Decrease it (down to 0.1s) for high-speed control loops — but keep in mind that very fast scan rates increase network and CPU load.

For detailed explanations of the on-demand settings (freshness, batch window) and how they affect AI model inference latency, see On-Demand Scanning.

Diagnostics

Parameter	Description	Default
Log Level	Controls the verbosity of per-device diagnostic logs. Options: Debug, Info, Warning, Error	Info
Tag Count	The total number of tags assigned to this device (read-only)	—

Metadata

Parameter	Description
ID	The device's internal database identifier
UUID	A unique identifier used in API calls and exports
Created At	When the device was first created
Updated At	When the device configuration was last modified

Protocol Parameters

In addition to the shared parameters above, each device has protocol-specific settings that define how Koios connects to the external system. These parameters only appear for devices using the corresponding protocol.

OPC-UA

Parameter	Description	Default
Endpoint	The OPC-UA server address (e.g. `opc.tcp://192.168.1.100:4840`)	—
Security Mode	Message protection level — None, Sign, or Sign & Encrypt	None
Security Policy	Cryptographic algorithm — None, Basic128Rsa15, Basic256, or Basic256Sha256	None
Token Type	Authentication method — Anonymous or Username/Password	Anonymous
Username	The account to authenticate as (only shown for Username/Password)	—
Timeout	How long to wait for the server to respond, in seconds	30s

For full setup instructions, see Creating an OPC-UA Device.

Modbus TCP

Parameter	Description	Default
Hostname	The IP address or hostname of the Modbus server	—
Port	The network port to connect on	502
Unit ID	The Modbus slave ID (0–255)	1
Timeout	How long to wait for a response, in seconds	5s
Show One-Based	When enabled, register numbers are displayed starting from 1 instead of 0	Off

For full setup instructions, see Creating a Modbus TCP Device.

EtherNet/IP

Common fields (both types):

Parameter	Description	Default
Hostname	The IP address or hostname of the device	—
Device Type	Logix Controller or Generic CIP	Logix Controller
Timeout	How long to wait for a response, in seconds	3s

Logix Controller additional fields:

Parameter	Description	Default
Controller Slot	The slot number where the controller is located in the rack	0

Generic CIP additional fields:

Parameter	Description	Default
EDS File	Electronic Data Sheet file for structured tag browsing (optional)	—

For full setup instructions, see Creating an EtherNet/IP Device.

SOAP (RDM)

Parameter	Description	Default
Hostname	The IP address or hostname of the SOAP device	—
Type	The device type — currently supports RDM (Resource Data Manager)	RDM
Timeout	How long to wait for a response, in seconds	5s
RDM Username	The RDM account username. Must have "Installer" access level to write values	—
RDM Web Authentication	Whether the RDM has web authentication enabled. When on, reads also require credentials	Off

For full setup instructions, see Creating a SOAP Device.

REST (CAREL BOSS)

Parameter	Description	Default
URL	The base URL of the REST API, including scheme (e.g. `https://192.168.1.50`)	—
Type	The device type — currently supports CAREL BOSS	BOSS
Auth Type	The authentication method — Username/Password	Username/Password
Username	The account to authenticate as	—
Verify SSL	Whether to verify the server's SSL certificate	Off
Timeout	How long to wait for a response, in seconds	5s
Max Retries	Number of retry attempts for failed requests (some devices need multiple retries)	5

For full setup instructions, see Creating a REST Device.

Microsoft SQL

Parameter	Description	Default
Driver	The ODBC driver used to connect	ODBC Driver 18 for SQL Server
Hostname	The SQL Server hostname or IP address	—
Database Name	The database to connect to	—
Username	The database account username	—
Timeout	How long to wait for queries to complete, in seconds	10s

For full setup instructions, see Creating a Microsoft SQL Device.

Parameter Mappings

Any device parameter — live or configuration — can be mapped to a tag. This lets you:

Record parameter values (like status or error codes) into the time-series database for historical analysis
Use parameter values in expressions or as inputs to AI models
Monitor device health trends over time (e.g. tracking overscan frequency)

To create a mapping, click the map icon next to the parameter in the Parameters tab. You'll be prompted to select or create a tag to receive the parameter's value.

On-Demand Scanning Troubleshooting a Device