Tags

A tag in Koios represents an individual data point — a temperature reading, a motor speed, a pressure setpoint, a database column value, or a calculated result. Tags are where real data enters and leaves the platform: AI models read from input tags and write predictions to output tags, trends chart tag values over time, and events fire when tag states change.

Tags can get their value from three different sources — a connected device, a computed expression, or an in-memory write from a service. See Tag Source Types below for details.

Input vs Output

Every tag has a usage that determines how Koios interacts with it:

Usage	Direction	Description
Input	Read from device	Koios reads this tag's value from the device on each scan cycle. This is the default for most tags — sensor readings, status registers, database values.
Output	Read and write	Koios can write values back to the device through this tag. Output tags receive values from AI models, mappings, or components, and push them to the device on the next scan.

Output tags still read

Output tags read their current value from the device on every scan, just like input tags. The difference is they can also receive a value to write back. This means you can see both the output value (what Koios wants to write) and the current value (what the device is actually reporting).

Usage is fixed for expression and in-memory tags

Expression tags are always read-only — they compute their value from a formula and have no device to write to. In-memory tags are always read/write — they receive output values from services (AI models, mappings, components) which write through them. Only device tags let you choose between input and output.

Tag Lifecycle

Tags follow a straightforward lifecycle:

Create — add a tag and configure its settings (device and protocol fields for device tags, an expression for expression tags, or just general settings for in-memory tags)
Enable — activate the tag so it begins collecting or computing values
Live — the tag's value updates on each scan or evaluation, is recorded to the time-series database, and is available to models, trends, and the rest of the platform
Stopped / Failed — a tag stops when disabled (or when its parent device stops, for device tags). It enters a failed state if it encounters an error.

Device tags follow their device

A device tag can only collect data when its parent device is enabled and running. If the device is stopped, all of its tags stop too — regardless of each tag's own enabled setting. Expression and in-memory tags have no parent device, so they operate independently.

Tag Status

Like devices, every tag has a real-time status:

Status	Meaning
Running	The tag is actively producing values — being scanned from a device, evaluated from an expression, or relayed from a service
Stopped	The tag is disabled (or its parent device is disabled, for device tags)
Failed	An error occurred — check the error code and message for details

When a device tag fails, the parent device may continue scanning its other tags normally. Tag errors are isolated — one bad tag doesn't bring down the whole device.

What You See on a Tag

The tag list table shows all tags across the platform. Key columns include:

Status — colored icon showing running, stopped, or failed
Name — the tag's unique name
Source — device, expression, or in-memory
Device — the parent device (device tags only)
Value — the current live value
Units — engineering units (°C, PSI, RPM, etc.)
Usage — input or output icon

You can filter by device, protocol, or search by name. Tags can be enabled, disabled, duplicated, or deleted in bulk.

Tag Detail

Clicking a tag opens its detail page with four tabs:

Overview — live status, current value with sparkline chart, device info, and recent events
Configuration — all editable settings (general, protocol-specific, and advanced)
Parameters — read-only table of every tag field, organized into live data, config, and protocol sections
Cross References — shows where this tag is used (AI models, mappings, components, etc.)

Configuration

General Settings

Setting	Description	Default
Name	Unique identifier for the tag	—
Description	Optional note about the tag's purpose	—
Enabled	Whether the tag is actively collecting or computing values	Off
Usage	Input (read-only) or Output (read/write)	Input
Decimal Places	How many decimal places to show for numeric values (0–3)	1
Units	Engineering units displayed alongside the value (e.g. °C, PSI)	—
Range Min / Max	Expected value range — used for normalization in AI models and display scaling	0–100

Protocol-Specific Settings

Device tags have additional configuration that depends on their protocol. These settings tell Koios where to find the data point within the device:

Protocol	Key Settings
OPC-UA	Namespace, node identifier, identifier type, data type
Modbus TCP	Register address, register type, data type, byte/word swap
EtherNet/IP (Logix)	Logix tag name, tag type
EtherNet/IP (Generic CIP)	Assembly instance, byte offset, data type, bit number
SOAP (RDM)	RDM device address, RDM parameter
REST (BOSS)	BOSS device address, variable code, variable type
Microsoft SQL	SQL query
See the protocol-specific tag creation guides for details on each.

Advanced Settings

Setting	Description	Default
Value Mapping	Maps raw device values to numeric outputs using ordered match rules	Off
Test Output	For output tags — write a fixed test value instead of the live output, useful for commissioning	Off
Write Always	For output tags — retry the last output value on every scan, even if no new value has been received	Off
Redundancy	Read from a device set instead of a single device, enabling automatic failover	Off

History Compression

By default, every tag uses the global compression settings configured on the Data Retention page. Global compression uses Swinging Door Trending (SDT) to discard values that don't meaningfully change the trend, reducing storage consumption while preserving the shape of the data.

If a specific tag needs different compression behavior, the History Compression section on the Configuration tab provides an Override global compression settings toggle. When enabled, three tag-specific settings appear:

Setting	Description	Default
Compression Enabled	Whether to compress this tag's history	On
Compression Deviation	Maximum deviation from the trend line, as a percentage of the tag's range	0.1%
Maximum Time Between Samples	Force a sample after this many seconds regardless of compression	60s

When the override is off, the tag follows whatever the global settings are — a link on the Configuration tab takes you directly to the Retention page to view or change them.

When to use per-tag overrides

Most tags work well with the global defaults. Use per-tag overrides when a tag has specific fidelity requirements — for example, a critical control signal that must record every change, or a slow-moving temperature sensor that can tolerate aggressive compression. Overrides are fully independent: changes to the global settings have no effect on overridden tags.

Range affects compression

SDT calculates the tolerance band as a percentage of the tag's Range Min / Max. If the range is left at the default 0–100 but the tag's actual values span a much narrower band (e.g. 0–1 or 4–20 mA), the tolerance band will be wider than the signal and almost nothing gets recorded. Always set each tag's range to match the actual expected value range. See Tag Range and Compression for details.

Tag Source Types

Every tag has a source type that determines where its value comes from. You choose the source type when creating a tag.

Source Type	Description	Has Device?	Usage
Device	Reads and writes values from a connected industrial device (OPC-UA, Modbus, etc.)	Yes	Input or Output
Expression	Computes its value from a formula that references other tags	No	Read-only
In Memory	Receives its value from a service — the predict engine, mapping service, or component engine	No	Read/Write

Device Tags

The most common type. A device tag belongs to a device and inherits its protocol. The device handles the connection, and the tag defines what to read or write within that connection — an OPC-UA node, a Modbus register, an EtherNet/IP controller tag, a SQL query, and so on.

Expression Tags

Expression tags compute their value from a formula evaluated by the Expression Evaluator service. Expressions can reference:

Tag values and status — the live value, status, or error code of any other tag
Device status — whether a device connection is running or failed
Model status — whether an AI model is running or failed
Binding values — the raw prediction value from a model output binding

This makes expressions useful for more than simple math — you can build logic that reacts to the health of devices or models, not just their data. Expressions support arithmetic, comparison, and logical operators, plus built-in math and statistical functions.

Expressions are evaluated in one of two ways:

Reactive — when any referenced tag's value changes, the expression re-evaluates immediately (within milliseconds)
Timer-based — if the expression has no reactive tag dependencies, it evaluates on a configurable interval (the Evaluation Rate field)

See Expression Tags for the full syntax reference.

In-Memory Tags

In-memory tags historize values written by the predict engine, mapping service, or component engine. These services write an output_value to the live data cache when they produce a result (e.g. a model prediction or a mapped value). Without an in-memory tag, that output value lives only in the cache and is never recorded.

The Expression Evaluator service monitors in-memory tags and relays output_value to the tag's live value, writing each update to the time-series database for historical storage. This relay happens two ways:

Event-driven — the producing service publishes a notification after writing, and the relay happens within milliseconds
Timer fallback — a periodic check (default 10 seconds) catches any missed notifications

In-memory tags also provide:

Status monitoring — the tag shows running/stopped/failed status like any other tag
Stale detection — if the source service stops writing, the tag enters a failed state after a configurable timeout (default 60 seconds), with a clear error message showing how long ago the last write occurred
Waiting state — before the source service writes for the first time, the tag shows a running status with an informational "Waiting for output value" message

When to use in-memory tags

Use an in-memory tag when you need to chart in trends or monitor the health of a value produced by the predict engine, mapping service, or component engine. If you only need the live value in the cache (for example, as an intermediate step in a pipeline), you don't need an in-memory tag — the output value is already available in the live data cache without one.

Output Conflicts

When multiple sources (an AI model, a mapping, and a component) all try to write to the same output tag, Koios flags an output conflict on the tag's overview page. This is a warning — only one source's value will be written per scan. Review the tag's cross references to understand what's writing to it and resolve any unintended overlaps.

Key Concepts

Concept	Description
Value	The tag's current reading — from a device, a computed expression, or a service write
Quality	For OPC-UA tags, the server-reported data quality (Good, Bad, Uncertain)
Timestamp	When the value was last updated
Range	The expected min/max values — used by AI models for normalization and compression band calculation
Compression override	Per-tag compression settings that override the global defaults
Value mapping	An ordered list of match rules that convert raw values to numeric outputs
Test output	A mode that writes a fixed value for commissioning output tags
Expression	A formula that computes a tag's value from other tags
Cross references	A view of everything that reads from or writes to a tag

What's Next

Creating a Tag — step-by-step guide to adding a new tag
Expression Tags — syntax reference for expression formulas
Value Mapping — mapping raw device values to numeric outputs
Troubleshooting a Tag — diagnosing errors and testing tag reads

Troubleshooting a Device Creating a Tag