circuitmatter 0.4.1

No project description provided

CircuitMatter

CircuitMatter is a Python-only implementation of the Matter IOT specification. It is aimed at hobby use and hasn't been certified for commercial use.

The Matter spec originates out of the Connected Home over IP (CHIP) project and some resources still use this naming. Matter is the trademark associated with certification.

Get the Matter Specification

The Matter specification is behind a contact info wall here: https://csa-iot.org/developer-resource/specifications-download-request/ CircuitMatter code is based on version 1.3 and references sections from that version.

You do not need to pay anything or be a member organization.

Running CircuitMatter

CircuitMatter is currently developed in CPython 3.12, the de facto implementation written in C. It runs in Python 3.11 as well. It is designed with minimal dependencies so that it can also be used on CircuitPython on microcontrollers.

Running on a Raspberry Pi SBC

CircuitMatter uses avahi tools to manage MDNS on Linux. It must therefore be installed for it to work properly.

sudo apt-get install avahi-utils

Now, install CircuitMatter:

pip install circuitmatter

The device demos use the Blinka library to interact with hardware via the CircuitPython API. Follow the instructions from the guide to install Blinka.

Blink

The simplest example connects an LED to Matter as an OnOffLight.

"""Simple LED on and off as a light."""

import circuitmatter as cm
from circuitmatter.device_types.lighting import on_off

import digitalio
import board


class LED(on_off.OnOffLight):
    def __init__(self, name, led):
        super().__init__(name)
        self._led = led
        self._led.direction = digitalio.Direction.OUTPUT

    def on(self):
        self._led.value = True

    def off(self):
        self._led.value = False


matter = cm.CircuitMatter()
led = LED("led1", digitalio.DigitalInOut(board.D13))
matter.add_device(led)
while True:
    matter.process_packets()

To change the behavior of a device, you subclass the CircuitMatter device class and implement the abstract methods and attributes it uses. These methods and attributes are then used during the process_packets() call depending on Matter interactions.

Save that as code.py (and on an SBC run it with):

python code.py

The first time this is run, it will generate all necessary pairing data and certificates. They are stored in matter-device-state.json in the current directory by default. They are loaded from that file on subsequent runs. Examples may use a unique file name so that different "devices" are separate on to other Matter devices.

The next step is to commission the device into your Matter Fabric from an app such as Apple Home. CircuitMatter will print a QR code to the console that you can scan to add the device. It also provides a setup code you can manually enter. Here is an example (that won't work for your code):

QR code data: MT:MNOA5N1527ZM192KI10
                             
                             
    █▀▀▀▀▀█  ▀▄█▀ █▀▀▀▀▀█    
    █ ███ █ ▄ █▄▀ █ ███ █    
    █ ▀▀▀ █ ▀▀ █▀ █ ▀▀▀ █    
    ▀▀▀▀▀▀▀ ▀ ▀ █ ▀▀▀▀▀▀▀    
    ▀█▄▄ █▀█▄▀▄ ▀  ▄▀▀ ▄     
    ▄▄▀███▀█▄▀ █▀   ▀▀▄▄█    
     ▀▀   ▀ ▄▀▄▀██▀█▀▀▀▄▄    
    █▀▀▀▀▀█ █▀█  ▄█▀  █▄█    
    █ ███ █   ▄█▄  ▀▄▄▄      
    █ ▀▀▀ █ ▄███▀ █▄▀█ ▀█    
    ▀▀▀▀▀▀▀ ▀  ▀▀   ▀▀       
                             
                             
Manual code: 0418-824-2967

NeoPixel

Setup is the same for the NeoPixel example.

"""RGB LED strip as a full color light."""

import circuitmatter as cm
from circuitmatter.device_types.lighting import extended_color

import board
import neopixel


class RGBPixel(extended_color.ExtendedColorLight):
    def __init__(self, name, pixels):
        super().__init__(name)
        self._pixels = pixels
        self._brightness = 0.1

    @property
    def color_rgb(self):
        return self._color

    @color_rgb.setter
    def color_rgb(self, value):
        self._pixels.fill(value)
        print(f"new color 0x{value:06x}")

    @property
    def brightness(self):
        return self._brightness

    @brightness.setter
    def brightness(self, value):
        self._brightness = value
        self._pixels.brightness = value
        print(f"new brightness {value}")

    def on(self):
        self._pixels.brightness = self._brightness
        print("on!")

    def off(self):
        self._pixels.brightness = 0
        print("off!")


matter = cm.CircuitMatter()
# This is a 8mm NeoPixel breadboard LED. (https://www.adafruit.com/product/1734)
# Any pixelbuf compatible strip should work. The RGBPixel class will control the
# entire strip of pixels.
np = neopixel.NeoPixel(board.D12, 1, pixel_order="RGB")
led = RGBPixel("led1", np)
matter.add_device(led)
while True:
    matter.process_packets()

On Blinka, you'll need to run it as root to control the NeoPixel. This can be tricky when using a virtual environment because you'll need to call the specific Python in that case.

sudo .venv/bin/python code.py

Developing CircuitMatter

Requirements

Install the dependencies from "Running CircuitPython".

Do a dev install

pip install -e .

Running a CircuitMatter replay

CircuitMatter can capture and replay UDP packets and random numbers to ease development. You can test the start of the CircuitMatter process by using the replay file from the repo:

python examples/replay.py test_data/recorded_packets.jsonl

Running for real

To run CircuitMatter against a live Matter commissioner run:

python examples/replay.py

This will start up MDNS via avahi for discovery by the commissioner and then reply to received UDP packets. CircuitMatter currently doesn't fully commission so it can't act as any specific type of device yet. When it can, there will be examples.

Running a Matter commissioner

chip-tool

The de facto standard implementation of Matter is open source as well. It is written in C++ and has many dependencies. It implements all of the different facets of the specification.

We use this implementation via ESP Matter (tested on commit 9350d9d5f948d3b7c61c8659c4d6990d0ff00ea4) to run an introspectable (aka debug printable) commissioner.

To setup esp-matter clone the repo and load submodules:

git clone -o espressif [e-mail]:espressif/esp-matter.git
cd esp-matter
git submodule update --init --recursive .

This will pull down the ESP Matter wrapper code and the projectchip implementation into the connectedhomeip/connectedhomeip/ sub-directory.

To build all of the command line tools run

bash install.sh

(Or source it directly if you use bash.)

Now setup the environment using export.sh. (This depends on what shell you use.)

Next, run chip-tool to initiate the commissioning process:

chip-tool pairing code 1 67202583

This will look up commissionable devices on the network via MDNS and then start that process. 67202583 is the manual pairing code that matches the device state in test_data/device_state.json.

Logs can be added into the chip sources to understand what is happening on the commissioner side. To rebuild, I've had to run bash install.sh again.

Apple Home

The Apple Home app can also discover and (attempt to) commission the device. Tap Add Accessory.

• By default this will pull up the camera to scan a QR Code. CircuitMatter will print the qrcode to the console to scan.
• You can also use the passcode by clicking "More options" and the CircuitMatter device will show up as a nearby Matter Accessory. Tap it and then enter the setup code 67202583. This will start the commissioning process from Apple Home.

iOS Chip Tool

The connectedhomeip repo also has an iOS version of Chip Tool that can be helpful in debugging Apple Home. Installation instructions (requiring xcode) are here: https://github.com/project-chip/connectedhomeip/tree/master/src/darwin/CHIPTool

Publish

To publish a new release, make a release through the GitHub CI. It'll push to PyPI.