Devices

What a device is, the settings every device shares, and how to choose a protocol.

A device is a piece of equipment in your building that THMI reads data from — a controller, meter, or sensor. You add the device once with its connection details, then create device tags on it for the individual values you want to collect. Each device tag corresponds to one value (a register, object, node, or topic) on that device.

Choosing a protocol

THMI talks to devices using the common building and industrial protocols. The protocol determines both how you connect to the device and how you address individual values. Pick the one your equipment speaks:

• Modbus — registers and coils over TCP.
• BACnet — building-automation objects, with optional change-of-value subscriptions.
• OPC UA — nodes over an OPC UA server, with anonymous, username, or certificate authentication.
• M-Bus — metering data over TCP or serial.
• MQTT — values published to topics on a broker.
• TwinCAT (ADS) — Beckhoff PLC symbols or direct addresses.

Each protocol page documents every device and tag setting it offers, and what each one does.

Settings every device shares

Whatever the protocol, a device has a few common settings:

• Name — how the device is identified in the project. You can also give it a custom name (a friendlier alias).
• Enabled — whether THMI establishes a connection to the device to receive data. Disable it to stop all communication with the device (and the collection of its tags’ values) without deleting its configuration.
• Host — the hostname or IP address used to reach the device on the network.

Most protocols also expose a timeout (how long to wait for a response) and a way to control how often values are read — see each protocol page for specifics.

Devices and their tags

Once a device exists, you create tags on it. Device tags share the common tag settings — values, formatting, limits, transformation, and history — on top of the protocol-specific addressing covered on each protocol page. A few concepts, below, are shared by every protocol; the protocol pages refer back here rather than repeat them.

Data types

A device tag’s data type tells THMI how to interpret the raw value it reads. The same set is available across protocols (which types a given address actually supports depends on the protocol and the address):

Each numeric and boolean type also has an array form (int array 16, float array, bool array, …) that reads several consecutive values into one tag. For an array type, the number of values setting controls how many consecutive values are read.

The data type also drives how a value is stored after transformation: integers are kept as int64, real numbers as double, and booleans as bool.

How values are read

Most protocols read a value one of two ways:

• Polling — THMI reads the value on a fixed polling interval (in milliseconds; 5000 = every 5 seconds by default). Always available.
• Subscription — the device pushes updates only when the value changes, which cuts network traffic for stable signals. Only some protocols (BACnet change-of-value, TwinCAT, MQTT) support it, and the device must support it too.

Reading and writing

A tag’s access mode is either read-only or read-write. A writable tag lets users with permission send a value back to the device (see Values). Writing is only possible where the protocol and the specific address allow it — read-only addresses (a Modbus input register, a BACnet input object, any M-Bus value) can never be written.

Health and bulk import

A device reports a health status (OK or error) so you can see at a glance whether THMI is communicating with it. To set up many devices and tags at once, you can import them in bulk from a file rather than creating each by hand.