Setup, concepts (edge, gateways, tags, and devices)

The other half of Setup: everything about getting real telemetry flowing from the shop floor into Spall, and operating that edge fleet once it’s running. See Setup for hierarchy/rates/workforce/access.

What’s in this area

Getting a gateway online for the first time? Bring a gateway online is the single start-here guide for the on-site path (flash → claim → configure → verify).

Domain objects

Gateways, sources, and tags

The chain: a gateway is an edge device physically on the floor (e.g. a Raspberry Pi at a line). A gateway has one or more sources, a connection to something that has data (a PLC, a sensor bus, an OPC-UA endpoint), each connection-testable (POST /sources/{id}/test-connection) before you trust it. A source exposes one or more tags, individual named signals (hydraulic_pressure, cycle_count). Gateways are scoped by site. A new source is added under a gateway and can be deleted, as can the gateway itself.

Tag Discovery

Instead of configuring tags blind, Tag Discovery lets an admin add candidate tag rows (id + address + type), set a sample interval and survey window, and have a source survey that bounded candidate set at low rate. The AI layer then scores each candidate, liveliness, redundancy, outcome alignment, into a keep / maybe / skip / abstain verdict, with per-tag evidence shown alongside the verdict. Two guarantees matter here: scoring alone never mutates config (survey config and the resulting report are separate from the source’s live tag config), and only an explicit promote action writes a tag into the source’s permanent config, the AI never acts on your behalf. Internally, survey config rides in the source’s connection_params.survey object. The report’s tag ids strip a survey: storage prefix used while candidates are still being evaluated.

Signal inbox and unclassified measurements

Auto-create means every tag a gateway captures becomes a measurement (a Signal) the instant it’s first seen, that’s what makes onboarding config-first: nobody has to name every tag before data starts flowing. The trade-off: a captured-but-unlabeled measurement is unclassified, and it stays quarantined from every KPI, alert, and ML feature until a human tells the system what it means. Classifying a measurement (PATCH /signals/{id} with a purpose) is what moves it out of quarantine, never automatic, never inferred on its own.

There are two surfaces for the same action:

• Signal inbox (/grooming, GET /api/v1/signals/unclassified), the global inbox: every unclassified measurement across every node in the tenant, in one fast, one-decision-per-row triage list. Per-node chips jump straight to the worst backlog. Quick-assign buttons cover the four most common meanings (Sensor reading, Run/stop signal, Part counter, Setpoint), with a grouped dropdown for the rest. The Signal inbox has no nav entry of its own, it’s reached from a badged card on Getting Started, the one place its live unclassified count shows. The zero-state, “Everything on the floor has a meaning,” is deliberate: working the inbox down is meant to be pleasant, not a chore layered on top of the real work.
• Node Detail → Measurements tab (/node/:type/:id?tab=measurements, GET /nodes/{id}/signals), the same classification action, scoped to one node, grouped into KPI drivers, Setpoints & control, Sensors, Derived, and Unclassified, needs a look. Each row has an Advanced ▸ wiring disclosure that the Signal inbox omits, the raw tag/gateway/source it’s mapped from, and (for a mapped measurement) an editable scale/offset conversion. This is also where a derived measurement is authored, an expression over other measurements, since the Signal inbox’s dropdown never offers “derived” as a choice: a calculated value isn’t a label applied to a captured tag, it’s built from measurements that are already classified.

The full set of meanings a measurement can be given: the KPI drivers are Run / stop signal, Part counter, Cycle time, Reject / scrap count, and Energy / power, these feed OEE and production math directly. Setpoints and control-loop signals are Setpoint, Process variable, and Control output. Sensor reading is captured for context and analytics, with no direct KPI role. Derived is the one meaning that’s authored, not picked, and only on the node itself.

Tags: mapped, derived, manual, and parameter

Mapped/Derived/Manual/Parameter are one kind-filtered Tags screen (/tags), scoped to a plant-tree node. A derived tag is computed from other tags via a formula, authored in its own full-page script editor (/scripts/new, /scripts/:signalId) that Tags links out to instead of editing inline. A mapped tag comes straight off a gateway source. The raw acquisition tags themselves (before anyone has classified them) live on the source’s own page under a gateway’s Sources & tags tab, not on Tags. See How to manage tags: mapped, derived, manual, and parameter signals.

The Config tab and pushing configuration

A gateway’s Config tab (/gateways/:gatewayId) is where its assembled configuration is previewed and pushed live (POST /gateways/{id}/config/push) so the edge agent picks up the change without a manual file copy. The UI reflects the push result. This is the mutation counterpart to the Tags screen’s read/edit view of what’s classified.

The Gateways list: lifecycle, drift, claim tokens, and data budgets

The Gateways list (/gateways) operates the edge device fleet as a whole, across every gateway for the tenant:

• Effective state and agent version, is a gateway online, and what build is it running.
• Config drift, a badge flags a gateway whose live edge config no longer matches what’s stored centrally.
• Buffer/gap health, whether the gateway’s local buffer is keeping up (no unresolved telemetry gaps).
• Network status, a self-reported “Network” line per gateway: the interface/IP carrying its default route (eth0 · 10.0.0.225 · default), or carrier/tech/signal on cellular (LTE ATT ▂▄▆ −71 dBm), best-effort via the on-device modem probe. An amber “fallback path” badge flags a default route that’s fallen off the wired uplink onto wifi/cellular. Null/absent means the gateway hasn’t heartbeated since this feature became available on its agent build. The failover/failback itself is a device-side policy: each interface has a declarative role (uplink/plant/disabled) and, for uplinks, a priority. NetworkManager enforces it (a plant interface can never capture the default route, the fix for the classic “OT DHCP hijacks the uplink” failure, and uplinks fail over/back by priority on their own). The reason for a failover (“wired lost carrier, failed over to wifi”) is readable on the device’s own console, and also surfaces directly on the gateway’s list card and Status tab, right next to the fallback-path badge, once the box has actually bounced or failed over at least once. See device offline or on cellular: reading the uplink status.
• Reported build vs. pinned target, the device’s agent_version is plain read-only status, never an input. To move a gateway toward a specific signed release, admin/super_admin pick one from a dropdown of published, signed releases only (no free-text version field, a typo can’t select a build that doesn’t exist) and click Pin. The card then reads update pending → vX until the device converges, or up to date otherwise. Still backed by PUT /gateways/{id}/target-version, the picker is what changed, not the endpoint.
• Claim tokens, a short-lived token (POST /fleet/claim-tokens, 60-minute TTL) minted to onboard a brand new physical device onto the tenant, without hand-editing config.
• Data budgets, a metered-link gateway can have a daily data budget (budget_mb_day, MB/day) configured inline. bytes_24h (bytes actually sent, trailing 24h) is compared against that budget to produce a status badge: within budget (under 80%), near budget (≥ 80%), or over budget (≥ 100%). A gateway with no budget configured shows “not set” instead of a made-up status. This exists for gateways on metered/limited-bandwidth links (e.g. cellular) where uncontrolled telemetry volume has a real dollar cost. The badge is informational. Enforcement/throttling of the link itself is a separate, edge-side concern.

Kiosk: Boards and Devices

Kiosk (/kiosk-screens, also reachable as Boards in the Floor nav group) holds two related but distinct jobs as tabs:

• Boards, a kiosk board is a named, sluggable wallboard configuration (slug, e.g. "floor") built as a drag-tile layout: pick which assets/measurements each tile shows, a refresh interval, and arrange the tiles. The resulting login-free wallboard itself renders at /kiosk/{slug} for anyone on the floor. See How to build a kiosk wallboard.
• Devices, where a tablet is claimed as a claimed station: mount /kiosk on the device, claim it, and it becomes a chrome-free entry point that fronts a machine, or a whole cell of machines. See How to run a claimed station.

How the pieces relate

Gateways and a gateway’s own Config tab are two views of the same underlying edge configuration, the Gateways list is where you register a device and its sources. The Config tab is where you preview and push that configuration live. Tags and Tag Discovery both deal with tags, but at opposite ends of a tag’s life: Discovery is how a brand-new candidate tag gets evaluated and promoted into permanent config. Tags is where every already -classified tag (mapped, derived, manual, parameter) is read and edited going forward. The Gateways list sits above all of this as the operational view, it’s where you’d notice a gateway drifted, is over its data budget, or needs a version bump, regardless of which of the other screens originally configured it. Kiosk’s Boards tab is one consumer-facing output of this whole chain: it maps configured assets (which only exist because a gateway/source/tag chain got them flowing) onto a public wallboard. Its Devices tab is a different consumer, claiming a tablet as a claimed station fronting a machine or a cell. The Signal inbox and the node Measurements tab sit just downstream of the tag chain itself: the moment a gateway/source/tag path is flowing, every tag it captures auto-creates a measurement, and classifying it, either in the Signal inbox or on a single node’s tab, is where that raw capture becomes something the rest of the app (KPIs, alerts, ML) is allowed to trust.