# Adapter Implementation Examples

## Purpose

This document captures practical implementation conventions that proved useful while building the `ZG-204ZV` adapters:

- Zigbee2MQTT -> HomeBus adapter

- HomeBus -> HomeKit adapter

It complements `addapters.md`.

`addapters.md` defines the normative adapter role and contract boundaries.

This document focuses on practical Node-RED integration patterns, cold-start behavior, flow topology, and known failure modes.

---

## Two Distinct Adapter Roles

In practice, two different adapter classes appear in the system:

1. ingress adapters

These consume vendor topics and publish canonical bus topics.

Example:

`zigbee2mqtt/ZG-204ZV/...` -> `vad/home/...`

2. consumer adapters

These consume canonical bus topics and project them into another consumer model.

Example:

`vad/home/...` -> HomeKit

Rule:

- keep ingress normalization separate from consumer-specific projection

- do not mix HomeKit, dashboard, or automation constraints into the ingress adapter

- treat HomeKit adapters as bus consumers, not as protocol translators

Pipeline:

Device -> Ingress Adapter -> MQTT Bus -> Consumer Adapter -> Consumer System

---

## Recommended Node-RED Flow Topology

### Ingress Adapter Pattern

Recommended structure:

1. dynamic or static `mqtt in` on vendor broker

2. adapter normalization node

3. `mqtt out` on canonical broker

4. optional debug nodes on raw input and normalized output

If the adapter controls vendor subscription dynamically:

- reserve one output for `mqtt in` control messages

- reserve one output for MQTT-ready publish messages

Practical convention:

- when an adapter has multiple semantic outputs, keep the `mqtt in` control output as the last output

- this keeps semantic outputs stable and makes flow rewiring easier

### Consumer Adapter Pattern

Recommended structure:

1. dynamic `mqtt in` on canonical broker

2. consumer adapter

3. consumer-specific nodes or services

4. optional debug nodes for `last`, `value`, and control messages

Typical example:

- subscribe to `.../last` and `.../value`

- use retained `last` for cold start

- continue on live `value`

- optionally unsubscribe from `.../last` after bootstrap completes

---

## Cold-Start Pattern with `last`

For stateful consumers such as HomeKit, a practical pattern is:

1. subscribe to `.../last`

2. subscribe to `.../value`

3. initialize consumer state from retained `last`

4. keep consuming live `value`

5. optionally unsubscribe from `.../last` after bootstrap completes

Example:

- subscribe `vad/home/balcon/+/south/last`

- subscribe `vad/home/balcon/+/south/value`

- wait until all required capabilities are satisfied

- unsubscribe `vad/home/balcon/+/south/last`

Bootstrap completion SHOULD be defined explicitly.

Good rules:

- all required capabilities have arrived from either `last` or `value`

- or the consumer has entered a known good state for its required capability set

Bad rule:

- unsubscribe on first live message only

That rule is incomplete because a single live message does not imply that the consumer has received all required initial state.

---

## Dynamic `mqtt in` Control Messages

For Node-RED dynamic `mqtt in`, control messages SHOULD remain simple.

Preferred forms:

```json

{

  "action": "subscribe",

  "topic": "vad/home/balcon/+/south/last",

  "qos": 2,

  "rh": 0,

  "rap": true

}

```

```json

{

  "action": "unsubscribe",

  "topic": "vad/home/balcon/+/south/last"

}

```

Practical recommendation:

- prefer one control message per topic

- do not rely on a single multi-topic control message unless runtime behavior is already verified in the target Node-RED version

This keeps behavior easier to debug and makes sidebar traces clearer.

---

## Dedicated MQTT Session Requirement for Retained Bootstrap

This was a critical lesson from the HomeKit consumer adapter.

If a dynamic consumer depends on retained `last` as its cold-start mechanism, it SHOULD use its own MQTT client session.

In Node-RED terms:

- give that dynamic `mqtt in` its own `mqtt-broker` config node

- do not share the same broker config with unrelated static or dynamic subscribers when deterministic bootstrap matters

Reason:

- broker config nodes in Node-RED represent shared MQTT client sessions

- retained replay behavior is tied to subscribe operations in that session

- when static and dynamic subscribers share the same session, retained bootstrap can become non-deterministic from the perspective of one consumer

Observed failure mode:

- a static debug subscriber on `.../last` receives retained messages

- a dynamic consumer on the same broker config subscribes later

- the consumer does not reliably observe the cold-start retained replay it expects

- later live updates re-publish `last`, creating the false impression that only live traffic works

Rule:

- consumers that require deterministic retained bootstrap SHOULD have a dedicated broker config

This is especially important for:

- HomeKit adapters

- dashboard cold-start consumers

- control nodes that reconstruct state from retained `last`

It is usually not necessary for:

- simple live-only debug subscribers

- low-value telemetry observers that do not depend on retained bootstrap semantics

---

## Practical Semantics: Raw vs Derived State

Adapters must be careful not to publish device-generated derived semantics as if they were raw truth.

Example from `ZG-204ZV`:

- raw Zigbee payload contains `presence`

- with `fading_time = 0`, that field is effectively raw motion detection

- canonical output should therefore be `motion/value`

- canonical `presence` should remain reserved for held or higher-level derived occupancy semantics

Rule:

- when a device field is operationally a raw signal, publish it as the raw canonical capability

- keep higher-level semantics for fusion, aggregation, or dedicated higher-level adapters

This prevents single-device vendor quirks from leaking into the semantic bus.

---

## Status, Errors, and Flow Observability

Adapter nodes SHOULD expose useful runtime status in the Node-RED editor.

Useful status content:

- detected devices count

- processed input count

- translated output count

- invalid topic count

- invalid payload count

- dead-letter count

Adapters SHOULD also surface problems through:

- `node.warn` for malformed input and validation failures

- `node.error` for internal exceptions

- `<site>/sys/adapter/<adapter_id>/error`

- `<site>/sys/adapter/<adapter_id>/dlq`

- `<site>/sys/adapter/<adapter_id>/stats`

Rule:

- errors should be visible both in operational topics and in Node-RED flow messages

That combination makes debugging much faster than relying on only one channel.

---

## Recommended Debug Setup During Implementation

While implementing a new adapter, use three debug perspectives:

1. raw ingress debug

What the source `mqtt in` actually receives.

2. control-path debug

What control messages are sent to a dynamic `mqtt in`.

3. semantic output debug

What canonical bus publications are emitted.

For consumers using `last` bootstrap, it is useful to have:

- one static debug subscriber on `.../last`

- one static debug subscriber on `.../value`

- one debug node on the dynamic `mqtt in` output

- one debug node on control messages

This makes it possible to distinguish:

- no retained message exists

- retained exists but the dynamic subscription did not activate

- retained exists but the consumer path is using the wrong MQTT session

- parsing or capability mapping is discarding the message

---

## Example Integration: `ZG-204ZV`

### Ingress Adapter

Source:

`zigbee2mqtt/ZG-204ZV/<site>/<location>/<device_id>`

Output:

- `.../value` for live semantic samples

- `.../last` retained for latest timestamped sample

- `.../meta` retained

- `.../availability` retained

- `.../sys/adapter/...` for operational topics

### Consumer Adapter

Source:

- `vad/home/<location>/<capability>/<device_id>/last`

- `vad/home/<location>/<capability>/<device_id>/value`

Output:

- HomeKit service updates

- dynamic `mqtt in` control for bootstrap subscribe/unsubscribe

Lessons learned:

- occupancy may need to be synthesized locally from `motion` and a fading timer

- numeric values may arrive as strings and should be normalized defensively

- bootstrap completeness must be defined per required capability set

- deterministic `last` bootstrap requires a dedicated MQTT session for the dynamic consumer

---

## Summary Rules

- ingress adapters and consumer adapters are different roles and should remain separate

- prefer one control message per dynamic subscription topic

- keep dynamic `mqtt in` control output as the last output when practical

- define bootstrap completeness explicitly

- do not unsubscribe from `last` on first live message alone

- use dedicated MQTT broker config nodes for dynamic consumers that depend on retained bootstrap

- expose operational errors both in `sys` and in Node-RED flow messages

- treat raw device-generated signals as raw semantics, not as already-derived business meaning