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.
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.
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.
CircuitMatter uses avahi tools to manage MDNS on Linux. It must therefore be installed for it to work properly.
sudo apt-get install avahi-utilsNow, install CircuitMatter:
pip install circuitmatterThe device demos use the Blinka library to interact with hardware via the CircuitPython API.
Follow the instructions from the guide to install Blinka.
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
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.pyInstall the dependencies from "Running CircuitPython".
pip install -e .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.jsonlTo run CircuitMatter against a live Matter commissioner run:
python examples/replay.pyThis 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.
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 [email protected]: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 67202583This 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.
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.
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
To publish a new release, make a release through the GitHub CI. It'll push to PyPI.
