ISA-95 and UNS topic designer

How the topics are made

The tool turns an equipment hierarchy into MQTT topic names for a Unified Namespace and into Sparkplug B group, edge node and device IDs. It only designs names: nothing connects to a broker, and the files you export are the only output.

The hierarchy (ISA-95)

• Levels after the role-based equipment hierarchy of ISA-95 / IEC 62264-1: Enterprise → Site → Area → work centers (Production line, Process cell, Production unit, Storage zone) → work units (Work cell, Unit, Storage unit). Below a work unit: the ISA-88 equipment and control modules, and “Asset / equipment”, a free type of this tool for machines and devices. Equipment levels may nest.
• Checks: a node must be below its parent’s level (a Site under a Production line is an error); a skipped level (a line straight under a site) is a warning, because that branch’s topics are one level shorter and wildcards by position (“+”) then miss it; a hierarchy that does not start at an Enterprise is a warning.
• unverified The level names were recalled from ISA-95 Part 1 and ISA-88, not read in the standards (which pair Production line with Work cell, Process cell with Unit and Storage zone with Storage unit, as recalled). The tool does not check those pairs.

Names → topic levels

1. Unicode NFC; spaces at both ends removed.
2. Lower case (when chosen; MQTT topics are case-sensitive, so “Line1” and “line1” would be two topics).
3. ASCII only (when chosen): letters decomposed (NFKD) and their accents dropped (Š → S, é → e), a few letters spelled out (ß → ss, Ø → O, Ł → L, Æ → AE, Þ → Th), every other character except A–Z, a–z, 0–9, “-” and “_” becomes a space.
4. Each run of spaces becomes the separator (“-”, “_”, or one space); repeated separators collapse to one and are removed at both ends.

A level typed under “Topic level” is used as typed (and checked). Errors: an empty level, “/” (it would split the level), “+” or “#”, a first level starting with “$”, the null character, a lone surrogate, a non-ASCII level when ASCII only is chosen, two children of one parent with the same level, a topic generated twice, a topic over 65535 bytes. Warnings: control characters and Unicode noncharacters (MQTT says they should not be used), spaces or capitals against the rules, a level longer than the limit, a topic longer than the warning size, a node whose level is also a namespace.

UNS topics

• Topic = prefix (optional) / enterprise / site / area / … / node / namespace / tag. Namespaces are your list (the example: _meta, state, telemetry, events, commands); a tag line must start with one of them.
• Templates: a section [Production line] gives every production line its tags; [class: reflow-oven] gives them to the nodes whose Template class is reflow-oven; a node’s own tags come last. A tag already given by an earlier section is not repeated.
• Subscriptions (MQTT topic filters): “+” matches exactly one level, “#” any number of levels including none and must be the last level; a filter whose first level is “+” or “#” does not match a topic starting with “$”. The tester checks the filter (a “#” not last or not alone, a “+” sharing a level) and counts the topics it receives.

Sparkplug B

• From the Eclipse Sparkplug Specification 3.0.0 (read in its source, github.com/eclipse-sparkplug/sparkplug, commit e45b610): topics spBv1.0/group_id/message_type/edge_node_id[/device_id] with NBIRTH, NDEATH, NDATA, NCMD (edge node), DBIRTH, DDEATH, DDATA, DCMD (device), and spBv1.0/STATE/sparkplug_host_id for the host application. group_id, edge_node_id and device_id are UTF-8 without “+”, “/” and “#”; group_id + edge_node_id must be unique, a device_id unique under its edge node. Metric names may use “/” as folders; . , \ @ # $ % ^ & * ( ) [ ] { } | ! ` ~ : ; ' " < > ? are discouraged in them. The specification gives no character rule for the host ID; the tool applies the same reserved characters, since it is a topic level.
• The mapping is FactoKit’s: one ISA-95 level gives the group_id, one the edge nodes and (optionally) one the devices; levels above the group are dropped or folded into the group ID, levels in between are folded into the next ID or dropped, levels below the device (or below the edge node without devices) become metric name folders. Topics of nodes above the edge node level (an area’s _meta, for example) have no place in Sparkplug B and are listed as not mapped. Tags of the command namespace are also written with NCMD / DCMD.
• The table under the mapping shows what every level becomes, for your choice and for the four presets side by side: which levels are kept as IDs, which are folded into an ID and which are lost.

Worked example (the tool’s example)

1. The illustrative “Example Electronics” has 29 nodes: two sites (Nordwerk and Südwerk), SMT areas with three SMT lines of five cells (Printer, SPI, Placement, Reflow, AOI), two placers under one Placement cell, and a Warehouse area with a component store (storage zone) holding a dry cabinet and a reel tower (storage units). With the default rules (lower case, “-”, ASCII only) Südwerk becomes sudwerk and SMT Line 1 smt-line-1; no errors, no warnings.
2. The templates give 90 topics, for example example-electronics/nordwerk/smt/smt-line-1/telemetry/oee and example-electronics/nordwerk/smt/smt-line-1/reflow/telemetry/zone-temperature (class reflow-oven); the longest is 93 bytes.
3. Subscriptions: example-electronics/+/smt/+/+/telemetry/# receives 24 topics (telemetry of every SMT cell and placer); example-electronics/nordwerk/+/smt-line-1/# receives 29; # receives all 90 and $SYS/# none.
4. Sparkplug B with preset 1 (group = site, edge node = line, device = cell, area folded with “_”): 4 edge nodes (nordwerk / smt_smt-line-1 …), 17 devices, 84 metrics and 85 topics including spBv1.0/STATE/mes; the 6 _meta topics of the enterprise, sites and areas are not mapped, and the enterprise level is lost.

Common mistakes

• Using names as typed: “SMT Line 1”, “SMT line 1” and “smt-line-1” become three topics for one line.
• Wildcards in a published topic, or “#” in the middle of a subscription (“site/#/state”): brokers refuse both.
• Topics that start with “/” or end with “/”: an empty first or last level, which subscriptions must then match too.
• Branches of different depth: “+/+/+/+/state” then misses the lines that have no area above them.
• Sparkplug IDs taken from long paths: they travel in every message; keep them short and unique.

Files

• Settings JSON (format factokit-uns-designer, version 1: the tree, the naming rules, the templates and the Sparkplug mapping), re-importable; the hierarchy as CSV in the import columns (other work center and work unit types are written as Line / Cell there) or as indented text with every type; the names CSV; the topics CSV (one row per topic: the levels, namespace, tag, Sparkplug B topic and metric, problems); a plain topic list; a topic map JSON; the Sparkplug B topics and metrics CSV and topic list. Nothing is stored by this file.
• Files: CSV, TSV and TXT are read as if pasted (UTF-8, UTF-16, otherwise Windows-1257). XLSX: choose the sheet and the columns or a cell range; formula cells use the value Excel last saved, dates are kept as text. Files up to 20 MB are read in this browser only and never uploaded.
• XLSX files are read with SheetJS Community Edition 0.20.3, Apache License 2.0 (license text at the end of this file).

Not verified

• The ISA-95 / IEC 62264-1 and ISA-88 level names and their pairs were recalled, not read in the standards.
• The MQTT rules (MQTT 3.1.1 and 5.0, section 4.7: lengths, forbidden characters, wildcards, “$” topics) were recalled; the specification could not be opened here. The topic matching agrees with Eclipse Paho’s topic_matches_sub on 633 cases.
• Sparkplug B: the rules above were read in the specification’s source (version 3.0.0); how brokers and host applications treat IDs the specification does not forbid (spaces, non-ASCII letters) was not tested.

Questions

What is a Unified Namespace (UNS)?

A Unified Namespace is one place, usually an MQTT broker, where every system of a plant publishes its current data under topics that follow the plant’s structure: enterprise/site/area/line/cell/… Instead of point-to-point connections between machines, MES, ERP and dashboards, each one publishes its own data once and subscribes to what it needs. The structure most often follows the ISA-95 equipment hierarchy, so the topic itself tells where a value comes from.

What do “+” and “#” mean in an MQTT subscription?

“+” stands for exactly one topic level: site/+/line1/# receives line1 of every area of the site. “#” stands for any number of levels, including none, and must be the last level: site/# receives site itself and everything below it. Both may appear only in subscriptions, never in the topic a message is published to, and neither matches a first level starting with “$”, which brokers use for their own topics such as $SYS.

Should topic levels be lower case and without spaces?

MQTT allows any UTF-8 text except the null character, and topics are case-sensitive, so “Line1” and “line1” are two different topics. A fixed rule, such as lower case with hyphens and ASCII letters only, avoids near-duplicates and problems in tools that handle spaces, accents or special characters badly. Whatever rule you choose, apply it to every name; this tool turns names into levels by such a rule and reports what it could not fix.

How does the ISA-95 hierarchy map to Sparkplug B?

A Sparkplug B topic has only three places for names: spBv1.0/group_id/message_type/edge_node_id/device_id. A common mapping takes the site as the group, a line as the edge node and a cell as the device; the enterprise is then left out (or folded into the group ID), an area between site and line is folded into the edge node ID, and assets below the cell become folders of the metric names, such as placer-1/state/status. The tool shows what each level becomes for any choice and checks the IDs: no “+”, “/” or “#”, group and edge node unique together, a device unique under its edge node.

Does this tool connect to my broker?

No. It designs topic names only: the hierarchy, the naming rules, the generated UNS and Sparkplug B topics and the subscriptions are computed in your browser, and the results leave it only as the files you export (JSON, CSV or a plain topic list). Use them to configure your broker, gateways or edge devices.