# Tags

Tags are declared in TOML files under a project's tags/ folder — any structure, loaded recursively. Each entry names a point, types it, binds it to a device address, and optionally opts into history.

## A tag file.

```toml
# projects/press-line/tags/hydraulics.toml
[[tags]]
name = "HeadPressure"
path = "press/hydraulics/HeadPressure"
data_type = "f32"
device = "press-plc"
address = "DB2.DBD26"
scan_group = "fast"
description = "Hydraulic head pressure at the platen"
eng_units = "psi"
history = { enabled = true, deadband_mode = "absolute", deadband_value = 0.5 }

[[tags]]
name = "PumpRunning"
path = "press/hydraulics/PumpRunning"
data_type = "bool"
device = "press-plc"
address = "DB1.DBX0.0"
scan_group = "normal"
```

## Field reference.

| Field | Default | Description |
| --- | --- | --- |
| `name` | `required` | Display name. |
| `path` | `required` | Slash-delimited path, unique within the project. Screens and the API address tags by it. |
| `data_type` | `required` | bool, i16, u16, i32, i64, f32, f64, or string. |
| `device` | `—` | A \[\[devices\]\] name from server.toml. Omit for a memory tag the gateway holds itself. |
| `address` | `—` | Driver-specific point address — grammar below. |
| `scan_group` | `"default"` | Scan-group label. OPC UA applies its configured interval; other adapters retain their device-level cadence. |
| `description` | `—` | Human-readable description. |
| `eng_units` | `—` | Engineering-unit metadata on the tag definition, e.g. psi, degC, or RPM. Not included in live TagValue payloads. |
| `kind` | `"control"` | "control" or "config" — classifies the tag for write auditing. |
| `history` | `—` | Per-tag historian settings — table below. |

Tag paths are per-project — two projects can both define `plant/Temperature`. Within one project a duplicate path (even across files) is rejected at publish.

## Data types.

`bool`, `i16`, `u16`, `i32`, `i64`, `f32`, `f64`, `string`. Choose a type supported by the adapter's conversion rules. Supported conversions can widen or narrow values; unsupported combinations can produce null or `bad` readings. For example: a BACnet Binary object's present-value is an enumerated 0/1 on the wire, so declare it `i16`, not `bool`.

## Address grammar by driver.

| Driver | Grammar | Examples |
| --- | --- | --- |
| S7 | `DB<n>.DB<X\|B\|W\|D><offset>[.<bit>][,S<N>\|,WS<N>]` | `DB1.DBX0.0 · DB2.DBD26 · DB8.DBB54,S20. Also I/E (inputs), Q/A (outputs), M (markers): I0.0, IW4, QD8, MB2; T5 and C10. S<N>: STRING, 2+N bytes; WS<N>: WSTRING, 4+2N bytes.` |
| EtherNet/IP | `Symbolic controller path` | `Motor.Speed · Program:MainProgram.Counter` |
| Modbus TCP | `<C\|DI\|HR\|IR><0–65535>[:<type>]` | `C/DI default to bool; HR/IR to u16. Suffixes: bool, u16, i16, u32, i32, f32, u64, i64, f64, str<N>. C/DI accept bool. u64 has no SCADA tag conversion. HR100:f32 · HR300:str8.` |
| OPC UA | `NodeId string` | `ns=2;s=Tank_Level · ns=0;i=2258` |
| MQTT | `Broker topic` | `plant/line1/temperature` |
| BACnet/IP | `<object>,<0–4194303>[:<property>]` | `AI/AO/AV, BI/BO/BV, MSI/MSO/MSV, DEV; full names such as analog-value, or numeric types 0–1023. AV,1 · AI,2:units · BV,3 · 2,5:85. Property defaults to present-value.` |
| sim | `Pattern name` | `Sine_Wave · Square_Wave · Sawtooth` |

BACnet properties: present-value (pv), units, object-name, description, status-flags, reliability, out-of-service, priority-array, relinquish-default, event-state, object-identifier, device-type, location, object-list, object-type, vendor-identifier, vendor-name, protocol-services-supported, protocol-revision, property-list; numeric codes or `property-<code>` also work. Connection settings are on [Devices & drivers](https://thermitescada.com/docs/device-configuration.md).

## Tags without a device.

Omit `device` and `address` and the gateway holds the value itself — useful for operator inputs, recipe staging, and inter-screen state. Memory tags are readable, writable, and historizable like any other tag.

```toml
[[tags]]
name = "TargetPressure"
path = "press/recipe/TargetPressure"
data_type = "f32"
eng_units = "psi"
```

## Per-tag history.

With the historian feature on and a PostgreSQL connection configured (see [Server configuration](https://thermitescada.com/docs/server-configuration.md)), add a history block to each tag you want recorded. Tags without that block are not recorded. Aggregation is computed at query time — there are no rollup jobs to configure.

| Field | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Record this tag when the historian feature is on. |
| `sample_mode` | `"on_change"` | Uses on_change sampling; other configured values fall back to on_change. |
| `sample_rate_ms` | `0` | Minimum source-time interval between archived native samples. 0 disables time-based throttling; quality and deadband rules still apply. |
| `deadband_mode` | `"none"` | "none", "absolute", or "percent". |
| `deadband_value` | `0.0` | Change threshold below which samples are dropped. |

```toml
[[tags]]
name = "OvenTemperature"
path = "oven/Temperature"
data_type = "f64"
device = "oven-plc"
address = "DB6.DBD8"

[tags.history]
enabled = true
sample_mode = "on_change"
sample_rate_ms = 1000   # throttle: at most one sample per second
deadband_mode = "absolute"
deadband_value = 0.5
```
