Glossary

Canonical terminology for meshtrap. All other documents defer here.

If a term is missing or unclear, fix it here first — don’t redefine in another document.

Hierarchy

• Central service — the SaaS platform that aggregates telemetry from networks and federates to downstream services like Trap.NZ. Open source; anyone may self-host. A default public instance is run by the meshtrap project.
• Org (Organisation) — the billing / ownership unit at the central service. May own one or many networks. Examples: DOC, a community trapping group, an individual.
• Network — a single LoRa trust domain. Has one K_admin and one current K_group. Owned by one org. Reports to one central service.
• Region — a logical subdivision of a network with exactly one hub. A network may contain many regions; each region’s hub manages the LoRa traffic in that geographic area.
• Cluster — one router and its child traps. Routers within a region form a router-tier mesh; clusters are the leaves.

Devices

• Node — any LoRa device on a network: a trap, a router, a hub, or a tech node. Every trap is a node. Every router is a node. Not every node is a trap; not every node is a router.
• Trap node (or just trap) — an endpoint with a reed switch or similar sensor on a physical trap mechanism. Reports open / closed / triggered. The primary subject of the system.
• Router node (or just router) — a node that relays traffic between traps and the hub. RX-always-on. Larger battery and solar than a trap. A router can also include trap-monitoring functionality on the same device.
• Hub node (or just hub) — the deployment-level authority. Holds the canonical map of nodes, runs the local web UI, optionally relays to a central service over MQTT. One hub per region.
• Tech node — a portable, handheld node carried by field technicians. Functions as a mobile router with elevated privileges (signed by K_field) for diagnostics and field servicing.
• Endpoint — a generic term for any node that is a leaf in the routing topology (does not relay traffic). In practice, traps are the endpoints.

Roles (firmware)

The firmware role is selected at provisioning time:

• ROLE = ENDPOINT — for trap nodes.
• ROLE = ROUTER — for router nodes.
• ROLE = HUB — for hub nodes (ESP32-S3 hardware family).
• ROLE = TECH — for tech nodes.

Roles (server-side RBAC)

See ../server/rbac.md for the full table. Briefly:

• Org Owner / Org Admin — manage an org and its networks.
• Network Owner / Admin / Operator — manage one network.
• Volunteer — log servicing events.
• Viewer — read-only.
• Public — anonymous, sees only what the operator has chosen to expose.

Cryptographic keys

• K_group — per-network symmetric key (AES-128). Encrypts and authenticates all routine traffic on that network.
• K_admin — per-network symmetric key (AES-128) held only by hubs. Signs privileged commands (key rotation, factory reset, router reassignment).
• K_field — per-network symmetric key (AES-128) held by hubs and tech nodes. Signs limited field commands (BLE wake, status request, servicing log). Decision pending whether this is split from K_admin; see D-02.

Protocol

• Frame — one LoRa packet on the wire. Consists of an envelope (clear header, authenticated as AAD) followed by an AES-CCM-protected ciphertext and a 4-byte MIC. Formatted per spec/frames.yaml.
• Envelope — the 12-byte clear header on every frame: ver, type, src, dst, seq. Cleartext but authenticated (AAD), so routers can forward without holding the destination’s key. The AES-CCM nonce is not part of the envelope and is not transmitted — it is derived (see nonce / dir).
• nonce — the AES-CCM nonce, src(4) || seq(2) || dir(1). Derived at both ends from fields already in the clear header plus the frame’s direction; never sent on the wire. Uniqueness comes from the monotonic per-source seq.
• dir — the 1-byte direction tag inside the AES-CCM nonce. 0 = uplink (toward hub), 1 = downlink. Determined by the message type’s direction. Prevents nonce reuse between the two directions.
• STATUS — routine check-in from a trap (message type 0x01).
• STATUS_ACK — router’s reply to a STATUS with the ack-requested bit set (0x02); may carry the config_pending flag.
• COMMAND — a privileged instruction delivered in an extended RX window (0x07). May require K_admin signature.
• COMMAND_ACK — endpoint’s confirmation that a COMMAND was applied (0x08).
• admin_mic — inner authentication tag inside a COMMAND: an AES-CMAC-128 (truncated to 8 bytes) over src || dst || cmd_type || cmd_seq || cmd_payload, keyed by K_admin or K_field. Proves the command came from an authorised hub/tech node, separately from the outer K_group frame MIC; an endpoint applies a COMMAND only if both verify.
• cmd_seq — monotonic per-hub command counter inside a COMMAND. The endpoint rejects cmd_seq ≤ last_applied_cmd_seq (replay protection at the command layer, distinct from the frame seq).
• config_version — counter the endpoint increments on every applied config-mutating COMMAND. Reported in STATUS_ACK (hub’s known value) and ANNOUNCE (endpoint’s actual value) so the hub can detect drift.
• JOIN / JOIN_ACK — bootstrap exchange when a node first comes up or after factory reset (0x03 / 0x04).
• ANNOUNCE — endpoint’s full self-description (location, firmware, capabilities) sent to a router (0x05).
• WHO_ARE_YOU — router’s request that an endpoint re-send its ANNOUNCE (0x06). Used after hub state loss.
• proto_role — the on-wire role byte in JOIN and ANNOUNCE: 1 = endpoint, 2 = router, 3 = tech. Distinct from the server-side RBAC roles; this is the node’s function in the radio topology (see Roles (firmware)).
• ROUTING_BEACON — router-tier distance-vector advertisement (0x10).
• ROUTER_UPLINK — router-to-router/hub frame carrying aggregated child traffic (0x11).
• ROUTER_DOWNLINK — hub-or-router-to-router frame carrying commands destined for a child endpoint (0x12).
• KEY_ROLLOVER — hub broadcast that activates a new K_group, signed with K_admin (0x20).
• HELP — orphaned-endpoint escalation broadcast (0x21).

Hub ↔ central service (MQTT and API)

The application-layer contract above LoRa. The hub speaks MQTT to the central service; clients speak REST/WebSocket. Authoritative schemas live in spec/mqtt.yaml and spec/api.yaml.

• MQTT direction — the {direction} component in an MQTT topic path, with values up (hub → central service) or dn (server → hub). Not the same as the LoRa-frame dir byte: dir distinguishes RF uplink/downlink to prevent nonce reuse; MQTT direction partitions hub-server topic flow. They share the word accidentally — never conflate.
• MQTT topic — JSON-encoded message under the path meshtrap/{org_id}/{network_id}/{region_id}/{direction}/{topic}. A leaf topic name (e.g. status, command, announce) often resembles a LoRa frame name but does not transport that frame verbatim: the hub may aggregate, filter, derive, or synthesise. For example, up/status carries per-node STATUS rollups, not raw STATUS frames; up/trigger is a derived event, not a frame at all.
• MQTT QoS class — project-defined aliases for MQTT’s standard QoS levels: telemetry (QoS 0, fire-and-forget), alerts (QoS 1, at-least-once), commands (QoS 2, exactly-once).
• per_hub_credentials — the MQTT authentication scheme. Each hub has its own MQTT credentials, never embedded in shipped firmware and rotatable. Distinct from K_admin / K_group / K_field, which are LoRa-layer keys and never leave the LoRa trust domain.

Operations

• Provisioning — writing keys, identity, role, and routing config to a node, usually via BLE from a phone running the deployment wizard.
• Deployment — physically installing a provisioned node at its intended site and confirming it has joined the network.
• Key rotation — replacing K_group (and optionally K_admin) across a network. Different from a network wipe.
• Network wipe — destructive; all node config is invalidated. Every node must be re-provisioned in person. Distinct from key rotation.
• Orphan — a node the hub has not heard from in longer than its expected check-in interval. May resolve itself, or may require a field visit.
• Adoption — the act of assigning an orphaned node to a new router (or accepting a HELP-broadcasting node into a router’s child list).
• Servicing — recording field maintenance against a node: trap reset, bait replenishment, lure change, battery swap. Logged via the /servicings API resource. Volunteers may submit servicing events with audit attribution; Network Operators and above may sync them. See ../server/servicing.md.

Identifiers

• Node ID — 32-bit value, displayed as AAAA-BBBB hex with a separator. Network-scoped: the same node ID may exist in two different networks without conflict. The central service uses the composite (network_id, node_id) as the global identifier.
• Composite resource path — central-service resources address into the hierarchy as (org_id, network_id, region_id, node_id). MQTT topic paths and REST URLs both follow this ordering.
• Spec version — semver tag on the spec/ tree. Firmware and server implementations both declare which spec version they implement.

Frequencies and PHY

• Band — 864–868 MHz (NZ ISM, matches EU868 hardware).
• SF — Spreading Factor (default SF9).
• BW — Bandwidth (default 125 kHz).
• TX power — default +14 dBm; legal up to +20 dBm in NZ.

What we don’t call things

• We don’t say “mesh” when describing the endpoint tier. Endpoints don’t multi-hop. Use “cluster-tree” or “router-tier mesh” if precision is needed. Product material may say “meshtrap” because that’s the brand — see ./CLAUDE.md for the honest-claims rule.
• We don’t say “device” when we mean “node.” Stick with the role names (trap, router, hub, tech) where possible; use “node” only when role is genuinely undetermined.
• We don’t say “gateway” — that’s LoRaWAN terminology. Our equivalent is “hub.”