Pairing and addressing
How endpoints are paired into the gateway registry, how identity is assigned and persisted, and the failure modes to check when a device is reachable but not registered.
| Document revision | r0.1-draft |
|---|---|
| Status | draft |
| Applies to | LS-WS-1G, LS-WS-2G, LS-WS-3G, LS-RC-16A, LS-RC-25A, LS-DIN-4CH, LS-SN-TH, LS-SN-MT |
| Regions | global |
| Published | Oct 15, 2026 |
| Review due | Apr 15, 2027 |
| Author | Engineering documentation (owner unassigned) |
| Reviewer | Engineering sign-off pending (reviewer unassigned) |
Pairing is the transaction that puts an endpoint into the gateway's registry and gives it a stable identity. It is deliberately a deliberate act rather than automatic advertisement: an endpoint that joins silently is an endpoint whose identity the site did not choose, and that is how two identical switches end up controlling each other's circuits.
Preconditions
- The gateway is powered and reachable on its local interface, with the node registry open for additions.
- Each endpoint is within a surveyed link of the gateway, mounted with its final enclosure and antenna orientation.
- A record of what each endpoint is expected to control exists, so identity can be assigned to meaning, not to whatever pairs first.
Pairing sequence
1. Put the gateway in pairing state
Open the registry on the local interface. Pairing is a bounded operation with a window; complete one endpoint per window so an unknown device cannot slip in beside it.
2. Trigger pairing on one endpoint at a time
Bring one endpoint into its pairing state and confirm it appears in the registry as a new, unidentified entry before assigning anything to it. Pairing two devices in the same window is the commonest cause of an ambiguous registry.
3. Assign identity and label
Give the endpoint a stable, human-meaningful identity (for a switch, the circuit it controls; for a sensor, the space it monitors) and record the physical location. The label is what operators and rules refer to later.
4. Confirm the link and the report
Hold the endpoint's intended state and confirm the gateway logs the change. If the device pairs but never reports, the pairing succeeded and the report path did not — re-check the registration rather than the pairing.
5. Persist the registry
Write the registry to the gateway's persistent store and re-read it after a reboot. A registry that survives pairing but not power-cycle has not actually been committed.
Addressing rules
- Identity is assigned by the site, not by the radio: two endpoints of the same model are indistinguishable on the air until they are labelled in the registry.
- An endpoint is referenced by its registry identity everywhere — rules, logs and field protocols — so renaming an endpoint later is a change to policy, not a cosmetic edit.
- Replacements inherit the identity of the device they replace, so a swap does not require rebuilding the rules that referenced it.
Failure modes
- Paired but absent from the registry: closed the window before committing, or the wrong gateway was in pairing state; re-open and re-pair.
- Reachable but unresponsive to rules: the endpoint is in the radio's view but not in the registry the rules resolve against.
- Two endpoints controlling one circuit: both were paired into the same window and one took the other's identity; re-pair one of them after removing it from the registry.
Placeholder — pending engineering sign-off: the pairing-window duration, the maximum registry size and the identity-length limit are not published yet and are set per SKU generation.
Limitations
- The identities, labels and windows above are described as behaviour; the exact values are per-SKU and will be published with the firmware revision they apply to.
- Registers and message layouts are not reproduced here. The authoritative field and register definitions live in the interface contract, which is owned by a second team — see MQTT, Modbus and BACnet.
What this document does not cover: the failure modes covered by a diagnostic procedure are in Diagnosis checklist, and the rule behaviour that consumes these identities is in Failover and local policy.