# Devices & drivers

Devices are declared in config/server.toml: a \[\[devices\]\] entry names the connection, picks a driver, and passes driver-specific settings in \[devices.config\]. Tags bind to a device by name. Seven drivers ship in the runtime.

## Every device entry looks the same.

```toml
[[devices]]
name = "press-plc"     # unique — tags reference this name
driver = "modbus"     # sim | s7 | cip | modbus | opcua | mqtt | bacnet
enabled = true       # connect at startup (default true)

[devices.config]     # driver-specific keys — tables below
host = "192.168.0.10"
```

How a tag names a point on each device — the `address` grammar — is covered per driver on [Tags](https://thermitescada.com/docs/tag-configuration.md).

## Simulated device

Generates read-only values without hardware. Tag addresses are patterns: Sine_Wave, Cosine_Wave, Triangle_Wave (f64), Square_Wave (bool), Sawtooth (i32), Random_Float (f64), Static_String (string). Use memory tags for writable gateway values.

| Key | Default | Description |
| --- | --- | --- |
| `update_rate_ms` | `1000` | Simulation update interval in ms (min 1). |

```toml
[[devices]]
name = "sim-plc"
driver = "sim"
[devices.config]
update_rate_ms = 500
```

## Modbus TCP

Polls coils, discrete inputs, and holding/input registers over Modbus TCP.

| Key | Default | Description |
| --- | --- | --- |
| `host` | `required` | Device hostname or IP. |
| `port` | `502` | Modbus TCP port. |
| `unit_id` | `255` | Slave/unit ID (0–255). |
| `poll_rate_ms` | `1000` | Polling interval (min 10). |
| `connect_timeout_secs` | `5` | Connection timeout. |
| `request_timeout_secs` | `3` | Per-request timeout. |
| `word_order` | `"big_endian"` | "big_endian", "little_endian", "byte_swapped", or "word_swapped" — for multi-register values. |

```toml
[[devices]]
name = "modbus-io"
driver = "modbus"
[devices.config]
host = "192.168.0.10"
unit_id = 1
poll_rate_ms = 250
```

Addressing
`HR100, HR100:f32, IR50:i16, C0, HR300:str8 — register prefix plus optional type suffix.`

## Siemens S7

Reads and writes S7 data blocks over ISO-on-TCP (port 102).

| Key | Default | Description |
| --- | --- | --- |
| `host` | `required` | PLC hostname or IP. |
| `port` | `102` | ISO-on-TCP port; use 10102 for the hydraulic-press simulator's published host port. |
| `rack` | `0` | PLC rack number (0–7). |
| `slot` | `1` | PLC slot number (0–31). |
| `poll_rate_ms` | `1000` | Polling interval (min 10). |
| `connect_timeout_secs` | `5` | Connection timeout. |
| `request_timeout_secs` | `5` | Per-request timeout. |
| `connection_type` | `"PG"` | "PG", "OP", or "Basic". |

```toml
[[devices]]
name = "s7-plc"
driver = "s7"
[devices.config]
host = "192.168.0.1"
rack = 0
slot = 1
```

Addressing
`DB1.DBX0.0 (bit), DB2.DBD26 (f32/f64 at byte offset), DB8.DBB54,S20 (string).`

## EtherNet/IP (CIP)

Reads and writes controller tags by symbolic name — Allen-Bradley Logix-class controllers.

| Key | Default | Description |
| --- | --- | --- |
| `host` | `required` | Controller hostname or IP. |
| `port` | `44818` | CIP TCP port. |
| `slot` | `0` | CPU slot used for connected messaging; does not replace route_path. |
| `route_path` | `—` | Unconnected route as port,link pairs, e.g. "1,0" for backplane port 1, slot 0. Required when reaching the CPU through a separate Ethernet module. |
| `poll_rate_ms` | `1000` | Polling interval (min 10). |
| `connect_timeout_secs` | `5` | Connection timeout. |
| `request_timeout_secs` | `10` | Per-request timeout. |

```toml
[[devices]]
name = "line-plc"
driver = "cip"
[devices.config]
host = "192.168.0.20"
slot = 0
```

Addressing
`Symbolic controller paths: Motor.Speed, Tank_Level, Program:MainProgram.Counter.`

## OPC UA

Polls and writes OPC UA server nodes. The integrated adapter uses security_mode = "none" and security_policy = "none"; it has no client certificate/key configuration for signed or encrypted sessions.

| Key | Default | Description |
| --- | --- | --- |
| `endpoint_url` | `required` | e.g. opc.tcp://host:4840. |
| `poll_rate_ms` | `1000` | Polling interval (min 10). |
| `connect_timeout_secs` | `10` | Connection timeout. |
| `request_timeout_secs` | `30` | Per-request timeout. |
| `security_mode` | `"none"` | Use "none" with this adapter; secure modes require client certificate material it does not configure. |
| `security_policy` | `"none"` | Use "none" with this adapter. |
| `auth` | `"anonymous"` | "anonymous" or "username". |
| `username / password` | `— / ""` | username is required when auth = "username"; password defaults to an empty string. |

```toml
[[devices]]
name = "press-opcua"
driver = "opcua"
[devices.config]
endpoint_url = "opc.tcp://192.168.0.30:4840"
security_policy = "none"
security_mode = "none"
```

Addressing
`NodeId strings: ns=2;s=Tank_Level or ns=0;i=2258.`

## MQTT

Subscribes to broker topics and maps payloads to tags. A tag's address is its topic; with the default json codec the payload is parsed as a JSON value matching the tag's data_type.

| Key | Default | Description |
| --- | --- | --- |
| `url` | `required` | mqtt://, mqtts://, ws://, or wss:// URL — the TLS schemes enable TLS defaults. |
| `client_id` | `""` | Client identifier presented to the broker. |
| `username / password` | `—` | Broker credentials, if required. |
| `keep_alive_secs` | `60` | MQTT keep-alive. |
| `connect_timeout_secs` | `10` | Connection timeout. |
| `request_timeout_secs` | `10` | Publish acknowledgment timeout. |
| `clean_session` | `true` | Start with a clean broker session. |
| `max_inflight` | `64` | Max unacknowledged messages. |
| `qos` | `0` | Subscription and publish QoS (0–2). |
| `codec` | `"json"` | Payload codec: "json" or "utf8". |
| `protocol_version` | `"v3.1.1"` | "v3.1.1", "v5", or "auto". |

```toml
[[devices]]
name = "broker"
driver = "mqtt"
[devices.config]
url = "mqtt://192.168.0.5:1883"
client_id = "thermite-gw-01"
qos = 1
```

Addressing
`The broker topic, e.g. plant/line1/temperature.`

## BACnet/IP

Reads and writes BACnet objects over BACnet/IP (UDP), addressing one controller directly by IP. Today the driver is unicast-to-a-known-IP: it does not run Who-Is discovery or register as a BBMD foreign device, so controllers behind a BACnet router (e.g. MS/TP segments) are not addressable through this adapter.

| Key | Default | Description |
| --- | --- | --- |
| `host` | `required` | Controller IP or hostname. |
| `port` | `47808` | BACnet/IP UDP port (0xBAC0). |
| `poll_rate_ms` | `1000` | Per-tag read cadence (min 10). |
| `apdu_timeout_secs` | `3` | Per-attempt APDU timeout. |
| `apdu_retries` | `3` | Retries after a timeout. |
| `device_id` | `4194303` | Local BACnet device instance the driver presents. |
| `vendor_id` | `65535` | Local vendor id in I-Am replies. |
| `max_apdu_length` | `1476` | One of 50, 128, 206, 480, 1024, 1476. |
| `write_priority` | `—` | Default write priority 1–16 for commandable objects; omit for none. |
| `who_is_timeout_secs` | `3` | Accepted in configuration; unused by the adapter's poll loop. |
| `bacpypes3_segmentation_quirk` | `false` | Compatibility workaround for bacpypes3 peers. |

```toml
[[devices]]
name = "ahu-1"
driver = "bacnet"
[devices.config]
host = "192.168.1.50"
poll_rate_ms = 1000
write_priority = 8
```

Addressing
`AV,1 · AI,2:units · BV,3 — object type, instance, optional property (defaults to present-value).`

## Connection status and polling.

- Drivers expose connection status and tag quality. Polling adapters publish `bad` quality on failed reads. For MQTT, monitor broker connection state as well as the last tag update.
- S7, EtherNet/IP, Modbus, and BACnet use the device's `poll_rate_ms`. MQTT is event-driven and the simulator ticks at `update_rate_ms`. OPC UA additionally supports per-tag intervals through [scan groups](https://thermitescada.com/docs/server-configuration.md).
- Set `enabled = false` to keep a device configured but disconnected — useful while commissioning.
