Everything is a tag

A tag is a named value at a path. It is the only data structure in JasperNode you really need to learn, because everything is one: sensor readings, setpoints, computed values, connector configuration, connector status, system metrics, even log buffers. They all live in a single in-memory tag tree.

Anatomy of a tag

A tag’s address — its Tag ID — is its path plus its name, joined with /:

factory/line1/temperature
└──── path ────┘ └─ name ─┘

Each tag carries three things: a value, live stats, and durable properties.

Value

Every tag has a value type, one of:

Type	Use
number	analog readings, setpoints, counts (64-bit float)
boolean	on/off, run/stop, alarms
string	states, labels, short text
bytes	binary payloads (frames, blobs)

A tag that has never been written reads as empty (no value) until its first write.

A numeric tag can declare a decimals precision. Rounding is applied before the engine decides whether the value changed, so a write that rounds to the same number produces no event and no subscriber churn.

Stats (the live record)

Every tag tracks, automatically:

• previous value, and timestamps for the current and previous change (ts, prevTs) and the last write (setTs);
• source — who set it: ui, script, system, an MQTT connector, a Modbus instance, and so on. Every write is attributed.

There is also a derived quality: good (a connected writer connector is producing it), stale (its writer disconnected but it has prior data), uncertain (linked but never written), or unknown (no connector linked — e.g. a script or UI value).

Properties (the durable metadata)

Properties change rarely and are saved with the tag:

• description — human text;
• valueType and decimals;
• script — the optional attached logic (see Logic & the Logic Cycle);
• connector linkage — which connectors touch the tag and in what role.

Paths, folders and the tree

Paths form a folder hierarchy you organise freely: factory/line1/, hvac/building_a/, modbus_data/vsd_ethernet/. Folders are just shared path prefixes — there is nothing to “create” beyond giving a tag a path.

Renaming or moving a tag keeps its identity: the IDE, the AI agent and anything subscribed to it follow the tag to its new id. Scripts are the exception — they reference tags by path in on() / read(), so the Rename dialog lists the scripts that would break and offers to update them.

Naming rules

A tag or folder name may use letters, digits, underscore and hyphen only — up to 64 characters per level and 255 for the whole path/name id. Spaces, punctuation and accented characters are rejected when you create or rename; put human-friendly wording in the tag’s description instead.

The IDE and the AI agent refuse a bad name up front and suggest a valid one. A tag whose stored name breaks the rule (from an older project) is skipped at start-up rather than deleted, and the start-up log names it with a ready-to-paste repair command — rename it and it returns with its values.

Wildcard subscriptions

Subscriptions use MQTT-style wildcards, which makes it easy to watch a whole area at once:

Pattern	Matches
factory/line1/temperature	exactly that tag
factory/+/temperature	temperature under any single sub-path (line1, line2, …)
factory/#	every tag anywhere under factory/

+ matches exactly one path segment; # matches the rest of the path and must be last. (Subscribing to the bare root # is not allowed — it would wake on every change in the system.) The IDE, the AI agent, connectors and scripts all use this same matching.

Tag spaces

The tree is split into user space and the system space (__sys/). The split is about who may write where:

Space	You can edit?	Holds
User space	Yes — fully	Your application: I/O, setpoints, computed values, logic. Any path not under __sys.
__sys/host/	No (regenerated each boot)	Host machine facts: a 1 Hz clock, OS, network, CPU/memory/disk
__sys/node/about/	No	Engine identity: version, uuid, load state
__sys/node/user/	Yes — the only editable __sys subtree	App config, connector configs and enable switches, tool parameters
__sys/node/service/	No (system writes only)	Connector status & diagnostics, manifests
__sys/node/stats/	No	Engine health: tag counts, Logic Cycle timing, heartbeat lateness
__sys/node/logger/	No	Log streams (debug / info / warning / error)

Two consequences worth internalising:

• You configure connectors by writing tags. Saving a Modbus instance in the IDE writes __sys/node/user/connectors/modbus/<id>/config; flipping its switch writes the sibling enabled tag. The AI agent does the exact same thing.
• Your project is what backup captures. A backup carries your user tags (with their scripts), each connector instance’s config under __sys/node/user/, and your saved flows; host facts, live status and stats are regenerated by the receiving node. See System tags for the full map.

Tags are saved as they change and come back on the next start — see Architecture → Persistence.

Try it in the IDE

Open the Tag Tree from the left rail. Expand __sys/host/clock to watch the live 1 Hz clock; expand a connector’s base path (e.g. modbus_data/…) to see field values update each cycle. Select any tag to edit its value, description and properties, or to attach logic.

System tags open the same way, but read-only — the pane says so, and the editable controls are greyed out. Their values come from the engine and its connectors, not from you.