Python Matter WebSocket Server
Project description
Python Matter Server
This project implements a Matter (formerly Home Assistant Connected Home over IP or CHIP) Controller Server using WebSockets.
:warning: This is under development and in very early stage!
Usage
To use the Matter Server using the Supervisor add-on is the recommended path (tbd).
Development
The Home Assistant Matter Server uses the Python CHIP Controller part of the open source Matter/Project CHIP repository. The project offers a IPython based REPL for testing/exploring. The REPL is also available as Python CHIP Controller REPL Add-on.
Prepare venv for the Matter Server
This Python Matter Server needs the CHIP Controller Python libraries. The CHIP Controller Python libraries come with the complete Matter SDK (CHIP stack) as a native C++ library. The CHIP Controller Python is not available on pip, and, because it comes with a native C++ library, is a platform dependent library. The Matter SDK allows to build a Python wheel for your platform.
To build the Python CHIP Controller follow the building instructions available at docs/guides/python_chip_controller_building.md.
Note the essential command is scripts/build_python.sh -m platform -i separate.
It builds the library in out/python_lib/, and creates a venv for you in
out/python_env/. If you update the Matter SDK git repository, make sure to
run this command again to rebuild the library.
If you already compiled the CHIP Controller Python libraries previously, you can activate the Python virtual environment using:
source ../connectedhomeip/out/python_env/bin/activate
Note: There is a bug with Apple M1 based systems: Pigweed currently uses Python
x86-64 via Rosetta. That causes problems when trying to build the Python
CHIP Controller. There are work arounds documented in GitHub issue #19134.
Make sure to not use -i separate and setup the venv separately as well.
Run from the source tree
The Server needs to be run in a Python environment where the Python CHIP Controller is installed. E.g.
Also make sure that the default storage location is present:
mkdir $HOME/.chip-storage/
With the following command the server can be run directly from the source tree.
python3 -m matter_server.server
On macOS you will have to run above command with 'sudo' as it requires to interact with BLE.
On Linux, make sure Bluetooth (bluez) is active and enabled before starting onboarding.
The client does not need to be run in the Python CHIP Controller environment. It can be run from the source tree using:
python3 -m matter_server.client
Build and install
nce you have a working Python CHIP Controller Python environment, switch to this repository and install this project as follows:
pip install .
Creating a test device
Instruction on how to create a test device can be found here.
Installing custom component in Home Assistant
Inside your Home Assistant development environment.
pip3 install -e ../python-matter-server
cd config
mkdir custom_components
cd custom_components
ln -sf ../../../python-matter-server/custom_components/matter_experimental .
You can now add the custom component via the UI. It's called Matter (experimental):
Commissioning a test device
You can use Home Assistant services to commission a test device.
Each time the server restarts you will need to provide it your Wi-Fi credentials via the matter_experimental.set_wifi service to be able to onboard Wi-Fi devices.
Once done, you can onboard devices by sending the content of a QR code to the matter_experimental.commission service. Get the QR code from your test device via the Matter REPL.
Using the Python CHIP REPL
Matter provides their own REPL that allows you to directly interact with the device controller. It's possible to start this and have it use the same storage as the server:
chip-repl --storagepath=$HOME/.chip-storage/python-kv.json
On MacOs you will have to run above command with 'sudo' as it requires to interact with BLE.
Deploying a new version
- Update Matter Server PyPI package
pyproject.tomlwith the new version. - Update custom integration
manifest.jsonwith the new version for bothrequirementsandversion. - Tag a new release in this repository with the new version.
Updating the Matter Server add-on
- Update the PyPI package version used by the Matter Server add-on by updating
MATTER_SERVER_VERSIONin theDockerfile - Bump the add-on version in
config.yaml - Add a new entry for the new add-on version in the changelog
CHANGELOG.md
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file python-matter-server-0.2.1.tar.gz.
File metadata
- Download URL: python-matter-server-0.2.1.tar.gz
- Upload date:
- Size: 103.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 11b66f083ecbbbd0b67ee7716af0a72695b8012c695bb4bd200477fb36a18cf5 |
|
| MD5 | f45d0a4c34df070086eefb2f76ea0add |
|
| BLAKE2b-256 | 699e6a04eb836870aa55b3ddbd8c462ee5bf42efe89e3f02b56eda41e11b5e6a |
File details
Details for the file python_matter_server-0.2.1-py3-none-any.whl.
File metadata
- Download URL: python_matter_server-0.2.1-py3-none-any.whl
- Upload date:
- Size: 114.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 5f9c4ee683916b062b9819beb897a3f07eaab128177bc8d474d8d9060f68169c |
|
| MD5 | b5e0c6e3955aa2056e9e2be8cac69da7 |
|
| BLAKE2b-256 | d5824eadfb49d167855f8d2276ad033bd1fa06d97ef4a096486723ac64cee422 |
