This small application can turn your Raspberry Pi into a Matter lighting device. Once setup and commissioned, it allows control of a configured GPIO pin via Matter on/off commands. The GPIO output can be used switch an LED or another device via a relay.
The application is based on CHIP's Linux Lighting App example. It used the WiringPi library to control the GPIO of Raspberry Pi.
Usage instructions are available below and on the wiki.
This snap is expected to work on the following Raspberry Pi hardware:
- RPi 5 Model B Rev 1.x
- RPi 4 Model B Rev 1.x
- RPi 400 Rev 1.x
- RPi CM4 Rev 1.x
- RPi 3 Model B Rev 1.x
- RPi 3 Model B Plus Rev 1.x
- RPi 3 Model A Plus Rev 1.x
- RPi CM3 Rev 1.x
- RPi Zero 2W Rev 1.x
Note: If you have one of the listed hardware, and this snap doesn't work on it, please open an issue.
sudo snap install matter-pi-gpio-commander
Starting with v2, the project uses the
character device
for gpio operations, so it's necessary to configure the chip to be
used. The chip number is set to 0
by default.
For example, to set the chip for the
/dev/gpiochip4
:
sudo snap set matter-pi-gpio-commander gpiochip=4
Currently, the options possible for of chip to be configured are 4
in case of using RPi5 and 0
for all the other legacy arm64 Raspberry Pis.
If for some specific case you want to use a different chip, you can set:
sudo snap set matter-pi-gpio-commander gpiochip-validation=false
Then you can set whathever chip you want.
To set the line 4
:
sudo snap set matter-pi-gpio-commander gpio=4
In case of using the v1.x.x
make sure to also grant the GPIO access.
By default, the lighting app runs as a service without any CLI flags.
The snap allows passing flags to the service via the args
snap option.
This is useful for overriding SDK defaults to customize the application behavior.
To see the list of all flags and SDK default, run the help
app:
$ matter-pi-gpio-commander.help
Usage: /snap/matter-pi-gpio-commander/x3/bin/lighting-app [opti
GENERAL OPTIONS
--ble-device <number>
The device number for CHIPoBLE, without 'hci' prefix, can be found by hciconfig.
--wifi
Enable WiFi management via wpa_supplicant.
--thread
Enable Thread management via ot-agent.
...
For example, to set Passcode for commissioning:
sudo snap set matter-pi-gpio-commander args="--passcode 1234"
For enabling Thread management:
sudo snap set matter-pi-gpio-commander args="--thread"
Note
For Thread management, the application needs to have access to the OpenThread Border Router (OTBR) agent via DBus. When using the OTBR Snap, this can be achieved by installing the snap and granting the necessary rights; refer to Thread.
For setting multiple flags, concatenate the arguments and set them together:
sudo snap set matter-pi-gpio-commander args="--thread --ble-device 1"
The snap uses interfaces to allow access to external resources. Depending on the use case, you need to "connect" certain interfaces to grant the necessary access.
The avahi-control is necessary to allow discovery of the application via DNS-SD:
sudo snap connect matter-pi-gpio-commander:avahi-control
Note
To make DNS-SD discovery work, the host also needs to have a running avahi-daemon which can be installed withsudo apt install avahi-daemon
.
Note
On Ubuntu Core, theavahi-control
interface is not provided by the system. Instead, it depends on the Avahi snap. To use the interface from that snap, run:sudo snap connect matter-pi-gpio-commander:avahi-control avahi:avahi-control
The gpio access is granted using the custom-device
, which declares a slot to expose the /dev/gpiochip*
device and also a plug to self connect.
This interface is auto connected when installing the snap from the Snap Store.
For manual connection:
sudo snap connect matter-pi-gpio-commander:custom-gpio matter-pi-gpio-commander:custom-gpio-dev
To allow the device to advertise itself over Bluetooth Low Energy:
sudo snap connect matter-pi-gpio-commander:bluez
Note
BLE advertisement depends on BlueZ which can be installed withsudo apt install bluez
.
Note
On Ubuntu Core, thebluez
interface is not provided by the system. The interface can instead be consumed from the BlueZ snap:sudo snap connect matter-pi-gpio-commander:bluez bluez:service
To allow communication with the OTBR Snap for Thread management, connect the following interface:
sudo snap connect matter-pi-gpio-commander:otbr-dbus-wpan0 \
openthread-border-router:dbus-wpan0
sudo snap start matter-pi-gpio-commander
Add --enable
to make the service automatically start at boot.
Query and follow the logs:
sudo snap logs -n 100 -f matter-pi-gpio-commander
For the following examples, we use the Chip Tool snap to commission and control the lighting app.
sudo snap connect chip-tool:avahi-observe
sudo chip-tool pairing onnetwork 110 20202021
where:
110
is the assigned node id20202021
is the default passcode (pin code) for the lighting app
Switching on/off:
sudo chip-tool onoff toggle 110 1 # toggle is stateless and recommended
sudo chip-tool onoff on 110 1
sudo chip-tool onoff off 110 1
where:
onoff
is the matter cluster nameon
/off
/toggle
is the command name. Thetoggle
command is RECOMMENDED because it is stateless. The lighting app does not synchronize the actual state of devices.110
is the node id of the lighting app assigned during the commissioning1
is the endpoint of the configured device
Build:
snapcraft -v
This will download >500MB and requires around 8GB of disk space.
To build for other architectures, customize the architectures
field inside the snapcraft.yaml and use snapcraft's Remote build.
Install it as described in the install section by replacing matter-pi-gpio-commander
with the locally built snap file name and setting --dangerous
flag.
This project includes an app to quickly verify the chosen pin and snap GPIO access control without using a Matter Controller. The app will toggle the output voltage of the pin to high/low periodically.
To use, install the snap and configure the GPIO as explained above.
Then, run it via sudo snap run matter-pi-gpio-commander.test-blink
snap command or directly:
sudo matter-pi-gpio-commander.test-blink