ADR 0012 — Matter bridge: pure-Go implementation, prioritized cluster subset¶

Historical paths. Since 0.74.0 the Matter stack is a dependency, not a subtree: it lives in the go-fabric module and internal/north/matter/ no longer exists in this repository. The paths below are left as they were when the decision was made — a record rewritten to match today's tree stops being a record. For where each piece lives now, see SPECIFICATION.md §6.

• Status: accepted
• Date: 2026-05-05
• Supersedes: refines SPECIFICATION.md §6 (Matter Bridge — intended scope + earlier 7-week estimate)
• Related: ADR 0001 (MIT), ADR 0007 (Strong model source interface), ADR 0010 (Discovery payload from model), SPECIFICATION.md §2.2 Non-Goals, §6 Matter Bridge

Context¶

The Matter bridge is the major v1.1 feature. SPECIFICATION.md §6 records intent ("native partial Go") but defers implementation form and underestimates effort (7 weeks). With v1.0 substantially complete, the implementation form must now be locked, the cluster subset finalised, and the existing custom/generic/calculated data-point surface mapped to concrete Matter clusters so the forward-compat hooks documented in SPEC §6.3 can be verified.

Three constraints frame the decision:

1. Distribution channels: OpenCCU-Loom ships as a Docker container, a Home Assistant Add-on (also a container under the supervisor), and a CCU/OpenCCU Addon (tarball into the CCU filesystem). All three are packaged units. The "single static binary" property is therefore valuable but not load-bearing — it's a build-output convenience, not a deployment requirement.
2. Resource envelope: the CCU3 / OpenCCU Addon path runs on 1 GB RAM, ARMv7 / Cortex-A7. Anything that adds a Node.js or Rust runtime there has to justify ~50–100 MB resident.
3. Device reality: the device population this daemon targets is Homematic / HomematicIP. The Matter clusters that have non-trivial matches against that population are a small subset of Matter 1.5.1, not the full cluster catalogue.

What changed since the spec was written¶

• The earlier SPEC Matter section listed 10 clusters at parity weighting; the actual mapping against OpenCCU-Loom's custom / generic / calculated DP surface (internal/model/{custom,generic, calculated}) shows that four cluster families plus a small set of measurement/binary clusters carry ~95 % of the semantic value. The remaining clusters are either redundant (Generic.Sensor variants → six Matter measurement clusters) or have no Homematic counterpart (Speaker, Pump).
• The forward-compat claim ("DataPointValueChangedEvent carries enough structural data") was a guess at write-time. With the model layer now implemented (Phase 2 done), we can verify it concretely through the mapping table in §6 of this ADR.
• Cluster set scoped down means "bridge endpoint topology" (one Bridged Device per Homematic device, one Endpoint per channel that exposes one of the mapped clusters) becomes the binding constraint — not cluster count.

Options considered¶

Option A — pure Go, hand-rolled¶

The Matter substrate (TLV codec, MRP, Secure Channel, Interaction Model, PASE/CASE, attestation chain, mDNS) is built in Go using stdlib + small pure-Go libraries.

• Pros: matches CGO_ENABLED=0, single static binary across all three distribution channels, no second runtime on the CCU Addon path, no second build toolchain in CI, no second security-patching pipeline. License-clean (MIT/Apache-2.0 deps only). Matches the aiohomematic-style ports & adapters architecture.
• Cons: no usable Go starting point. All Matter Go projects on GitHub are toy-status. Spake2+ is not available as a pure-Go library. AES-CCM is not in stdlib. Realistic effort 12–16 weeks solo, not the 7 weeks in the earlier SPEC estimate.

Option B — matter.js sidecar (Node.js, Apache-2.0)¶

Daemon spawns and supervises a matter.js sidecar; communication via local-loopback WebSocket / JSON-RPC; daemon stays the single configuration / observability surface.

• Pros: mature implementation, broad cluster coverage, BLE commissioning available, certification-test-suite-aware. Time-to-v1.1 ≈ 4–6 weeks.
• Cons: adds a Node.js runtime to every distribution channel, ~50–100 MB RSS on the CCU Addon path (precedent exists via redmatic / Node-RED but it's still meaningful), introduces a third API surface (the sidecar IPC) that must be versioned and tested, doubles the security-patching pipeline, breaks the single-binary build output. Process-supervision and crash-recovery code becomes a real package, not boilerplate.

Option C — connectedhomeip via CGo¶

Reference SDK linked into the daemon.

• Pros: certified reference impl.
• Cons: violates the no-CGo rule (would require a separate ADR rolling back ADR 0001's spirit), ARM cross-compile of the C++ tree is painful, license (Apache-2.0) is fine but the dep tree is large. Not a serious option for this project.

Option D — rs-matter sidecar¶

Rust sidecar instead of Node.js.

• Pros: smaller footprint than Node, Apache/MIT.
• Cons: less mature than matter.js, second toolchain (Rust for arm/v7) added to release pipeline, all of Option B's downsides except the resident-memory size.

Decision¶

Adopt Option A: pure Go, hand-rolled, with a tightly prioritized cluster subset.

The subset (§5) is small enough that the substrate cost (the bulk of the work) is no longer disproportionate to the cluster yield — once the TLV / MRP / Secure-Channel / IM substrate exists, adding clusters is schema-mapping work measured in days, not weeks.

Commissioning is on-network only in v1.1. No BLE in v1.1. BLE commissioning is the largest single cost driver outside the substrate itself; deferring it removes a Bluetooth stack from scope and lets v1.1 ship.

Effort revision: the earlier SPEC estimate of 7 weeks is replaced by a realistic 12–16 weeks solo for v1.1 (pure-Go substrate + P0 clusters + on-network commissioning + chip-tool conformance smoke). P1 and P2 clusters slot into v1.1.x point releases.

Prioritized Matter cluster subset¶

The cluster set is the narrow superset of (clusters with a non-trivial Homematic mapping) ∩ (Matter clusters HA / Apple / Google bridge UIs actually consume today). Cluster IDs and revisions from Matter 1.5.1 spec; the cluster shapes for the listed clusters are stable between 1.3 and 1.5.1, so the table below remains accurate.

Tier P0 — v1.1 GA¶

Required for the four device families the user identified (Light, Switch, Cover, Thermostat) plus the support clusters they need to be useful in HA / Apple Home / Google Home.

Tier P1 — v1.1.x point releases (high yield, low marginal cost)¶

Cluster mappings against existing generic/calculated DPs that "fall out" once the substrate is in place.

Tier P2 — v1.2+ (lower yield, more code per cluster)¶

Out of Matter scope (no v1.x mapping)¶

Custom / Generic / Calculated DP ↔ Matter cluster mapping table¶

Guiding principle: rich model, dumb bridge¶

Following ADR 0011 (MQTT) and ADR 0010 (HA Discovery), the projection from a DataPoint to a Matter endpoint/cluster lives on the DataPoint itself, not in the bridge. The bridge knows Matter wire format; the model knows what each DP means in Matter terms.

Concretely:

• A Custom DP declares its Matter device type and the cluster set it contributes via interface methods on the Go type — same pattern as payload.HAComponent() for MQTT (see internal/model/custom/light/topology.go).
• A Generic DP declares its Matter measurement class via a typed classifier (the same ParameterClass already used by the MQTT payload-routing layer), so a temperature-Sensor and a humidity-Sensor are not switch-statement-matched by name in the bridge.
• A Calculated DP declares its target cluster + attribute on the calculated-DP definition next to the formula, so adding a new calculated sensor does not require touching the bridge.
• The Matter bridge is a generic transport: TLV codec, MRP framing, Secure Channel, IM dispatcher. It owns no cluster-attribute switch statements. It iterates the model and asks each DP what it projects to.

The mapping table below is therefore the specification of those in-model declarations — every row corresponds to a method/declaration that lives in the corresponding model package, not in internal/north/matter/. Every DP type currently in internal/model/{custom,generic,calculated} is accounted for. "Endpoint type" is the Matter Bridged Device Type the source DP materialises as.

Custom DPs — bridged-device endpoint per *Channel¶

Generic DPs — endpoint contribution per *Channel¶

Generic DPs are attribute carriers, not endpoint types of their own. The bridge groups them by (channelAddress, parameterClass) and materialises them as additional clusters on the channel's endpoint, or as standalone sensor endpoints when the channel has no Custom DP.

Calculated DPs — derived sensors, no own endpoint¶

Calculated DPs are virtual sensors materialised on the source channel's endpoint (or rolled up to the device's first sensor endpoint when no channel applies). They do not introduce new endpoints.

Implementation strategy¶

Repository layout¶

Following the SPEC §6.1 placeholder direction and the rich-model principle (§6 introduction), the work splits into two layers:

Bridge layer — generic Matter substrate, no domain knowledge:

internal/north/matter/
├── server/                — fabric, sessions, message dispatcher
├── transport/             — UDP/IPv6, MRP, message framing
├── secure/                — Spake2+ (PASE), Sigma (CASE), session keys
├── tlv/                   — TLV codec
├── im/                    — Interaction Model (Read/Write/Subscribe/Invoke/Report)
├── cluster/               — cluster *protocol* impls (wire format, attr/cmd IDs)
│   ├── onoff/             — encode/decode OnOff cluster, dispatch by attr/cmd ID
│   ├── levelcontrol/
│   ├── colorcontrol/
│   ├── windowcovering/
│   ├── thermostat/
│   ├── booleanstate/
│   ├── occupancysensing/
│   ├── tempmeasurement/
│   ├── humiditymeasurement/
│   ├── illuminancemeasurement/
│   ├── doorlock/
│   ├── smokecoalarm/
│   ├── powersource/
│   └── core/              — Descriptor, Binding, BasicInfo, BridgedDeviceBasicInfo, GeneralCommissioning, NetworkCommissioning, GeneralDiagnostics, OperationalCredentials, GroupKeyMgmt, OTARequestor (stub)
├── endpoint/              — endpoint topology assembly: walks the model, asks each DP for its projection, wires cluster servers
├── commissioning/         — on-network discovery, attestation, fabric join
├── mdns/                  — DNS-SD operational + commissionable
├── attestation/           — DAC/PAI/PAA chain validation
└── store/                 — fabric / NOC / shared-secrets persistence (SQLite-backed via internal/store)

The cluster packages contain only the protocol — TLV encoding of attribute reads, command dispatch tables, report shape — and call back into the model via the source interfaces below to fetch values or apply writes.

Model layer — declares what each DP projects to:

internal/model/
├── custom/
│   ├── switch/    matter.go   — declares OnOffPlugInUnit + OnOff cluster projection
│   ├── light/     matter.go   — Light/ColorTemp/Color/RGBW/FixedColor projections
│   ├── cover/     matter.go   — Cover/Blind/Garage projections (Lift, Lift+Tilt, EndProductType)
│   ├── climate/   matter.go   — Thermostat + UI-Config + Temp/Humidity composition
│   ├── lock/      matter.go   — DoorLock projection
│   └── siren/     matter.go   — OnOff + BooleanState (Siren) / SmokeCOAlarm (SmokeSiren)
├── generic/
│   └── matter.go              — ParameterClass → Matter measurement-cluster routing
└── calculated/
    └── matter.go              — per-CalculatedParameter cluster + attribute declaration

pkg/interfaces/matter.go ceases to be a placeholder and gains the source-surface port shapes (next subsection).

Source surface (Go interfaces)¶

Mirrors the ADR 0011 pattern (payload.HAEntity, payload.Slotted, payload.DiscoveryDynamic). Lives in pkg/interfaces because both the bridge (internal/north/matter) and the model (internal/model/...) need to declare dependencies on the same types.

// matter.EndpointSource is implemented by Custom DPs that materialise
// as their own bridged endpoint. The endpoint assembler walks the
// model and creates one Matter endpoint per implementer.
type EndpointSource interface {
    // MatterDeviceType is the Matter Device Type ID
    // (e.g., 0x010A OnOffPlugInUnit, 0x0301 Thermostat).
    MatterDeviceType() uint16

    // MatterClusterServers returns the cluster-server contributions
    // this DP exposes on its endpoint. Order does not matter; the
    // endpoint assembler deduplicates.
    MatterClusterServers() []ClusterServer
}

// matter.ClusterServer is implemented by anything that contributes a
// Matter cluster — a Custom DP, a Generic DP grouped onto an
// endpoint, or a Calculated DP exposing a derived attribute.
type ClusterServer interface {
    // MatterClusterID identifies the cluster (e.g., 0x0006 OnOff).
    MatterClusterID() uint32

    // MatterRead resolves an attribute value at read time. The
    // returned value is in the cluster's native type (bool, uint8,
    // int16, etc.); the bridge handles TLV encoding.
    MatterRead(attrID uint32) (value any, ok bool)

    // MatterWrite applies an attribute write. The bridge has already
    // decoded the TLV; `value` is the cluster-native type.
    MatterWrite(ctx context.Context, attrID uint32, value any, priority hmenum.CommandPriority) error

    // MatterInvoke dispatches a cluster command. `fields` is the
    // cluster-native struct for the command's request payload.
    MatterInvoke(ctx context.Context, cmdID uint32, fields any, priority hmenum.CommandPriority) (response any, err error)

    // MatterReportable lists attribute IDs that emit reports when
    // the underlying DP fires OnEvent. Empty slice = none.
    MatterReportable() []uint32
}

// matter.MeasurementClass classifies Generic.Sensor / BinarySensor
// instances by Matter cluster without name-matching. The model layer
// computes this once at materialisation; the bridge consumes it.
type MeasurementClass int

const (
    MeasurementNone MeasurementClass = iota
    MeasurementTemperature        // 0x0402
    MeasurementHumidity           // 0x0405
    MeasurementIlluminance        // 0x0400
    MeasurementPressure           // 0x0403
    MeasurementCO2                // 0x040D
    MeasurementPM25               // 0x042A
    MeasurementPM10               // 0x042D
    MeasurementOccupancy          // 0x0406
    MeasurementContact            // 0x0045 (BooleanState, ContactSensor endpoint)
    MeasurementLeak               // 0x0045 (BooleanState, WaterLeakDetector endpoint)
    MeasurementBattery            // 0x002F (PowerSource)
    MeasurementPower              // 0x0090
    MeasurementEnergy             // 0x0091
    MeasurementMomentarySwitch    // 0x003B (Button/Action events)
)

// matter.MeasurementSource is implemented by Generic / Calculated DPs
// that project to a single Matter measurement cluster. The bridge
// uses this to either build a standalone sensor endpoint or attach an
// extra cluster to an existing host endpoint.
type MeasurementSource interface {
    MatterMeasurementClass() MeasurementClass
}

Compile-time assertions in each model package (var _ matter.EndpointSource = (*Light)(nil)) keep the model honest as the bridge layer evolves — the same discipline ADR 0011 introduced for payload.HAEntity / payload.Slotted.

Crypto strategy (the three real risks)¶

Forward-compat verification (replaces the SPEC §6.3 promise with measurement)¶

• Every Custom DP has a non-empty mapping in §6 → SPEC §6.3's DataPointValueChangedEvent / DeviceCreatedEvent / DeviceRemovedEvent shape is sufficient for endpoint build/teardown. Confirmed.
• Generic DP Parameter→Cluster routing rides on the same ParameterClass classifier already used by internal/payload (MQTT routing). The Matter MeasurementClass enum (§"Source surface") is computed from ParameterClass once at materialisation by the model layer — no per-publish lookup, no name-matching in the bridge. Confirmed.
• Calculated DPs sit on top of the same OnEvent plumbing as Generic sensors. Each calculated parameter declares its MatterMeasurementClass() on the Go type next to the formula, so adding a new calculated sensor is a model-package change, not a bridge-package change. Confirmed.

No model-layer structural refactor is required. The forward-compat work is additive: each model package gains a matter.go file implementing the source-surface interfaces from §"Source surface". The Matter bridge itself owns no DP-specific code — it iterates the model and dispatches via the interfaces.

Risks¶

1. Spake2+ correctness (highest). The verifier is a one-author cryptographic implementation. Mitigation: port from the CHIP reference and lock against chip-tool's published test vectors as golden tests; gate releases on a chip-tool pairing smoke run.
2. Spec drift: Matter 1.3 / 1.4 / 1.5 introduce new mandatory attributes. Mitigation: pin to Matter 1.5.1 for v1.1.0. Rationale: (a) Apple Home / Google Home / SmartThings have moved aggressively to 1.4/1.5, so a 1.3-only bridge would surface as version-mismatch warnings; (b) the clusters this bridge actually emits (OnOff, LevelControl, ColorControl, WindowCovering, Thermostat, DoorLock, BooleanState, BasicInformation, BridgedDeviceBasicInformation, Descriptor, the measurement clusters) have stable mandatory-set shapes between 1.3 and 1.5.1 — the 1.4/1.5 expansions land in Energy / EVSE / Cameras, all out-of-scope. © The protocol substrate (Spake2+, CASE / Sigma, AES-CCM, IM, MRP) is unchanged since 1.0. Cluster servers carry their 1.5.1 ClusterRevision; BasicInformation.SpecificationVersion advertises 0x01050100. Never advertise an unsupported version.
3. Endpoint topology size: a CCU with 200 devices × ~3 channels = ~600 bridged endpoints. Matter spec allows 256 endpoints per node by default; the bridge may need to advertise multiple bridge nodes per CCU. Mitigation: stress-test the assembler at the largest known fleet; open ADR 0012a only if topology partitioning becomes necessary.
4. HA Matter Server divergence: Home Assistant's Matter Server has bridge-specific quirks (e.g. it sometimes ignores Reachable=false for fast-cycling sensors). Mitigation: HA + Apple Home + Google Home all run as conformance targets in the release checklist; ship-blocking issues are filed against the controller, not papered over.
5. Effort underrun: solo full-time estimate is 12–16 weeks; at the project's part-time pace expect 2×. Mitigation: phase boundaries are independently shippable — substrate plus chip-tool commissioning is a demoable milestone before any cluster work.

Consequences¶

Positive¶

• Single static binary preserved across all three distribution channels. No second runtime on CCU3 hardware.
• Architecture stays uniform: Matter is a north-bound adapter on the same EventBus as MQTT and REST. Forward-compat from SPEC §6.3 is verified by §6 mapping, not assumed.
• Cluster prioritisation matches the actual Homematic fleet — no "we built it but nothing maps to it" clusters in v1.1.

Negative¶

• Significantly higher implementation cost than Option B (15 weeks vs. 4–6). The earlier SPEC estimate was wrong; this ADR records the right number.
• Spake2+ is a one-author cryptographic implementation. That carries audit weight (see §Risks). Counter-balance: the alternative (matter.js) is also single-vendor and not formally audited either.
• Effects, sound players, irrigation valves, and text displays do not surface to Matter — Matter has no clusters for them. The MQTT bridge remains the only path for those features. We document this clearly in the user-facing v1.1 release notes.

Migration¶

• pkg/interfaces/matter.go graduates from placeholder to public port surface (cluster source-surface contracts).
• internal/north/matter/ is created; SPEC §6.1's prior prohibition is lifted for the v1.1 line.
• assets/openapi.yaml gains /api/v1/matter/... endpoints (fabrics list, setup-payload, open-commissioning-window) under feature flag matter.enabled. Each route returns 503 service_unready when the bridge is disabled.
• The conformance test corpus lives at internal/north/matter/conformance/ (revised from the original tests/conformance/matter/ plan to keep the corpus next to the packages it exercises).

Follow-ups¶

• A separate ADR (0012a) is opened only if the endpoint-count ceiling (Risk #3) forces multi-bridge topology partitioning. Until then the assembler's stress-tested 600-endpoint capacity covers every fleet observed.