[ddwrt] Add client inventory and new-client event
## Summary
Expose a network-wide client inventory and a trigger for clients that have never previously been observed by the DD-WRT binding.
This is distinct from presence tracking for an existing client Thing: a client Thing's `online` channel answers whether a configured client has arrived or departed, while a new-client event should indicate that an unknown identity has appeared on the network for the first time.
## Current Behavior
The network bridge exposes aggregate wired, wireless, and total client counts. Discovery can submit enriched clients to the inbox, and accepted client Things expose individual presence and connection details.
There is no channel that lists the clients known to the binding and no rule trigger that distinguishes a newly observed identity from a known client coming back online. The discovery inbox is a configuration workflow and is not a suitable rule event source.
The UniFi binding similarly exposes client Things and aggregate counts, but does not provide an equivalent inventory or first-seen trigger to use as a precedent.
## Proposed Behavior
Add network-bridge capabilities along these lines:
- An advanced, read-only `client-inventory` channel containing a structured JSON snapshot of known clients.
- A `new-client` trigger channel fired only when a client identity not already present in the persistent inventory is first observed.
- Continue using individual client Things and their `online` channels for known-client arrival and departure tracking.
An inventory entry should contain useful fields when available, for example:
- stable identity
- hostname and enriched label
- current MAC and IP address
- online state and connection type
- access point, SSID, and radio channel
- first-seen and last-seen timestamps
- identity/name source where useful for diagnostics
The trigger payload should be structured enough for a rule to identify and report the new client, preferably JSON using the same field names as the inventory entry.
## Identity and Lifecycle Semantics
- Persist the known-client identity set across binding and openHAB restarts. Otherwise every restart would incorrectly report all existing clients as new.
- Treat the first successful inventory scan as a baseline without firing a notification for every existing device.
- Prefer a configured mapping or enriched stable hostname as identity when available, with MAC as a fallback.
- Do not report a client as new merely because its randomized MAC changed. This is important for phones that use different private MAC addresses when moving between radios or SSIDs.
- Enriching or renaming an existing inventory entry should update that entry rather than create a second identity or fire another new-client event.
- Update the inventory channel only when its meaningful content changes, rather than on every device polling interval.
- Produce the JSON in deterministic order so unchanged inventories do not create state churn.
Clients that lack any stable identity beyond a randomized MAC may need to be marked as uncertain or handled conservatively to avoid repeated false notifications.
## Example Inventory
```json
[
{
"id": "pixel-8",
"hostname": "pixel-8",
"label": "Pixel 8",
"mac": "aa:bb:cc:dd:ee:ff",
"ip": "192.168.1.42",
"online": true,
"connectionType": "wireless",
"ap": "office-ap",
"ssid": "home",
"firstSeen": "2026-08-29T14:20:00Z",
"lastSeen": "2026-08-29T15:10:00Z"
}
]
```
## Acceptance Criteria
- Rules can retrieve a structured list of clients known to the network bridge.
- A rule can trigger when a previously unknown client is first observed.
- A known client reconnecting does not produce a new-client event.
- Restarting openHAB does not reproduce new-client events for the established inventory.
- A learned randomized-MAC change for the same hostname does not create a duplicate inventory entry or event.
- The initial baseline does not flood the event bus with notifications for all existing clients.
- Tests cover initial baseline creation, restart restoration, known-client reconnects, genuinely new clients, enrichment, and randomized-MAC changes.
## Environment
- openHAB 5.2 and current development branch
- DD-WRT, OpenWrt, and compatible Linux network devices
0 条评论