Skip to content

matter-bridge 0.1.0

Latest

Choose a tag to compare

@github-actions github-actions released this 20 Nov 04:47
· 17 commits to main since this release

The first release of matter-bridge: a Matter controller and a Matter to MQTT bridge in Rust, built on rs-matter, as one static binary with no runtime.

Read this first

  • Device attestation is not verified yet. A Matter commissioner should check that a device is a certified product (its attestation certificate chain and certification declaration). matter-bridge cannot yet, so it accepts unverified devices: allow_unverified_attestation in [matter] must stay on, and the bridge logs a warning for every device it commissions. Only commission devices you trust.
  • GitHub release binaries only, no crates.io release yet. The crates depend on rs-matter pinned to a git commit, whose controller side is newer than its last release.
  • Thread commissioning is tested only up to the request that hands the border router's dataset to the device: CI has no Thread device.
  • Not built yet: more than 64 live nodes at once, OTA, sleepy (ICD) devices, and exposing other devices as a Matter bridge.
  • Early. CI commissions and controls connectedhomeip's reference device on every commit, but commercial devices have not been tested yet. Please report how it goes.

What you can do with it

  • Commission Matter devices onto a fabric of the bridge's own with their QR or manual pairing code: over IP, found by DNS-SD, or over Bluetooth LE, giving the device Wi-Fi credentials or the Thread border router's dataset. CI commissions the reference device over IP and a Wi-Fi device over Bluetooth between simulated controllers (Bumble); neither path has been tried with commercial devices yet.
  • Run the fabric's CA your way: a file CA for a standalone install, or an intermediate CA under a root held elsewhere (an HSM, a platform service). A commissioning in progress can be aborted.
  • Add devices you already use in Apple Home, Google Home or Home Assistant, with a pairing code from that app, and share the bridge's devices with them through commissioning windows (multi-admin).
  • Read, write and invoke on any cluster, in JSON, with names from the CSA's data model.
  • Put endpoints in groups and switch them together with one multicast command (Groupcast on Matter 1.6 nodes, Groups and Group Key Management on older ones).
  • Get every attribute change and event on MQTT, through a subscription to each device that is renewed when it lapses, and lights, switches and sensors in Home Assistant through MQTT discovery.
  • Run it on small hardware: about 2.7 MB (aarch64) and 3.6 MB (mipsel) static binaries, and 5.8 MB resident with 100 nodes in the store.

Install

Static binaries for x86_64, aarch64 (Raspberry Pi 3 and newer, 64-bit OS) and mipsel (MT7621/MT7628 routers) are attached below, with SHA256SUMS. The quick start goes from download to a device in Home Assistant; the documentation covers installation as a service, commissioning, configuration and every MQTT topic.

For developers

matter-controller is the controller as a library, and matter-model the Matter data model with JSON to TLV conversion. Depend on them by this tag; see the library guide.

All changes

Added

  • matter-model: the Matter data model as tables generated from the IDL
    rs-matter ships, and JSON to TLV and back.
  • matter-controller: onboarding (QR and manual codes), DNS-SD discovery,
    commissioning over IP on rs-matter's commissioner, a pluggable CA with a
    file CA, the node store, read, write, invoke, subscriptions with renewal,
    events, enhanced commissioning windows for multi-admin, and
    Controller::abort_commissioning.
  • Commissioning over Bluetooth LE (feature ble, on by default), with
    bluetooth-bridge's bluetooth-host as the GATT central under rs-matter's
    BTP: bluetooth = "hci0" or "tcp:host:port".
  • Network commissioning for devices reached over Bluetooth: the controller
    reads the device's Network Commissioning features and gives it the Thread
    dataset (thread_dataset, thread_dataset_url or the configured border
    router) or the Wi-Fi network (wifi) the commission request carries, inside
    the fail-safe, before CASE. Datasets and passphrases are never stored or
    logged.
  • Groups: Controller::add_to_group gives a node the fabric's group key and
    puts an endpoint in a group (Groupcast on Matter 1.6 nodes, Groups and Group
    Key Management before), with access for the group to operate it;
    group_invoke sends one multicast command to every member.
  • IntermediateCa: a controller under a root CA elsewhere, its intermediate
    key made and kept here, signing its own and its devices' certificates from a
    node id range the root CA assigns; Config.ca picks it or the file CA.
  • x509::to_matter_tlv: X.509 DER certificates in the Matter profile to
    Matter TLV, each checked by rebuilding the signed DER.
  • matter-bridge: the standalone MQTT bridge with Home Assistant discovery,
    including add_to_group, remove_from_group and group_invoke requests.
  • CI against connectedhomeip's all-clusters app (commissioning over IP, reads,
    subscriptions, writes, invokes, a group command, MQTT, a second admin), a
    Bluetooth commissioning test on a virtual controller pair (Bumble) with a
    Wi-Fi device, fuzzing of the JSON encoder, onboarding codes, Thread datasets
    and X.509 conversion, static aarch64 and mipsel builds with a size budget,
    and a memory budget.

Known limitations

  • Device attestation is not verified yet; allow_unverified_attestation
    must stay on.
  • Not on crates.io: rs-matter is a git dependency pinned to a commit.
  • Thread commissioning is tested only up to the request it sends; CI has no
    Thread device.
  • Not built yet: more than 64 live nodes, OTA, ICD devices, exposing other
    devices as a Matter bridge.