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.

Read vs Read/Write

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

Usage	Direction	Description
Read	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.
Read/Write	Read and write	Koios can write values back to the device through this tag. These tags receive values from AI models, mappings, or components, and push them to the device on the next scan.

The create form labels these Read-Only and Read/Write. The API uses the underlying names Input and Output. In a CSV import or export the usage column carries the numbers instead — 0 for Read, 1 for Read/Write. See Importing and Exporting Tags.

Read/Write tags still read

A Read/Write tag reads its current value from the device on every scan, just like a Read tag. The difference is that it 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: 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.

Tag Lifecycle

Tags follow this lifecycle:

Create: add a tag and configure its settings (device and protocol fields for device tags, an expression for expression tags, or 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. The available columns are:

Status: colored icon showing running, stopped, or failed
ID and Name: the tag's numeric ID and unique name
Description: the tag's optional note
Value: the current live value, formatted to the tag's decimal places
Range Min / Range Max: the tag's configured range
Usage: Read or Read/Write
Source: device, expression, or in-memory
Device, Protocol, Connection, Device Set: where the tag reads from
Last Scan, Created, Updated: timestamps

Use the show/hide menu in the toolbar to choose which of these are visible.

Search matches on name or description. You can filter on Status (which filters on live status, not the enabled setting), Name, Description, Usage, Source, Device, Protocol, Device Set, Created, and Updated.

Selected tags can be enabled, disabled, exported (config or data), or deleted in bulk. Duplicate is a per-tag action — right-click a row, or use the menu on the tag's detail page.

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	Read (read-only) or Read/Write	Read
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
Use Redundant Device	For device tags: read from a device set (with automatic failover) instead of a single device	Off

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
Decimal Places	How many decimal places to show for numeric values (0–3)	1
Value Mapping	Maps raw device values to numeric outputs using ordered match rules	Off
Write Always	For output tags: retry the last output value on every scan, even if no new value has been received	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	Read or Read/Write
Expression	Computes its value from a formula that references other tags	No	Read
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 a referenced tag updates, the expression re-evaluates immediately (within milliseconds). Referencing a tag's status or error code counts, not just its value
Timer-based: if the expression references no tags at all, it evaluates once per second

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 60 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 surfaces a warning after a configurable timeout (default 24 hours) while staying in a running state. Marking it failed would stop the producing model, so a stale value stays running with a warning showing how long ago the last write occurred
Waiting state: before the source service writes for the first time, and whenever it has no value to pass on (a mapping whose source tag is failing, for example), the tag shows a running status with no value and the warning "No output value — ensure tag is bound to an enabled model, mapping, or component connector"

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
Last reading	The reading a failed device tag last took, set apart from a current value. A tag whose device has failed keeps it as its value; a tag whose own read failed has no value for mappings, expressions, or models, and shows the reading for context only
Quality	How far the latest reading can be trusted. A running OPC-UA tag carries the server's status name, such as Good or UncertainLastUsableValue; a tag whose read fails carries Bad
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
Bad, Missing, or Frozen Tag Values: diagnosing errors and testing tag reads

Device Sets Creating a Tag