---
title: "Device Parameters"
description: "Reference for all device parameters — live data, configuration, and protocol-specific settings"
source_url: https://ai-ops.com/docs/devices/device-parameters
---

# 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](https://ai-ops.com/docs/devices/troubleshooting.md)) |
| **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 |

> [!TIP] 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 | — |

> [!NOTE] 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](https://ai-ops.com/docs/devices/on-demand-scanning.md#on-demand-freshness).

### 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](https://ai-ops.com/docs/devices/creating-opc-ua.md).

### 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](https://ai-ops.com/docs/devices/creating-modbus-tcp.md).

### 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](https://ai-ops.com/docs/devices/creating-ethernet-ip.md).

### 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](https://ai-ops.com/docs/devices/creating-soap.md).

### 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](https://ai-ops.com/docs/devices/creating-rest.md).

### 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](https://ai-ops.com/docs/devices/creating-mssql.md).

---

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