search

project-chip / matter.js

A complete typescript implementation of the Matter protocol specification (https://buildwithmatter.com). Includes full support for controller, device, commissioning, secure communications, device types, and cluster definitions.
Apache License 2.0
346 stars 59 forks source link
connectedthings iot matter matterprotocol smarthome

readme

JavaScript/TypeScript based Matter Implementation

license

What is Matter?

Matter is a new secure, reliable and local standard protocol for smart/IoT devices launched at the end of 2022 by the Connectivity Standards Alliance.

To learn more about Matter visit https://csa-iot.org/all-solutions/matter/

What is matter.js?

matter.js is a TypeScript/JavaScript implementation of the complete Matter protocol.

Our main goal is to create a robust and compliant library that enables the seamless implementation of Matter-compatible devices, bridges, controllers, and a shell application. This effort is dedicated to improving Matter's accessibility for testers, smart home enthusiasts, and developers of OS-based IoT products. Fostering a second implementation of the Matter standard, aligned with the same specifications, not only expands the ecosystem but also contributes to the validation and increased robustness of the standard itself.

matter.js consists of a set of pure JavaScript base packages without any native dependencies, implementing the Matter protocol and required interfaces in JavaScript, along with extensive typings for The Matter standard and the matter.js APIs. Further packages with Node.js based native dependencies utilize the base package to implement platform-specific parts using Node.js for networking and other necessary native features or add BLE support. Node.js example scripts implement example CLI scripts for Devices, Bridges or Controllers. A Matter Shell allow to interact with Matter devices as controller via a CLI interface.

To use matter.js in your own Non-Node.js based projects you need to implement the platform specific parts. See How to use matter.js in own projects for more details. If you do this please contact us to add your platform to the list of supported platforms.

matter.js employs code generation approaches to ensure a comprehensive model of all Matter Clusters and (soon) device types. This includes typing and documentation, readily available within developers' IDEs, facilitating easy accessibility and adherence to conformance information during coding. This approach allows for easy addition of new clusters and device types, ensuring synchronization with the Matter standard.

What matter.js can be used for?

matter.js serves various purposes and can be employed for:

Explore the versatile capabilities of matter.js and adapt it to your specific use cases!

Note on Certification

If you plan to officially certify a device, bridge or controller based on matter.js please contact us via E-Mail or Discord to get the latest information of the certification status of matter.js, supported and not yet supported features and consulting on the certification process.

matter.js successfully passed certification already. There are still thinks to consider and to discuss when you plan to certify.

Compatibility to Matter Standard

The Matter standard evolves continuously and delivers two updates per year. matter.js tries to follow the standard as closely as possible. The following list provides an overview which matter.js version is implementing which Matter standard version:

Compatibility to Ecosystems

Devices created with matter.js/matter-node.js have been tested with:

Matter.js based projects show up as "uncertified test devices" in the ecosystems. This is because the devices are not certified by the Connectivity Standards Alliance (CSA) and are not part of the official Matter certification program. However, the devices are fully functional and can be used in the ecosystems. The ecosystems usually inform the user about the uncertified status of the device. Please see Pairing and Usage Information for more details.

We also collected a list of tested device types on ecosystem.This is a compilation of published information by the ecosystems and own community tests.

Each ecosystem have their own specialities, see Pairing and Usage Information for more details.

When you plan to use matter.js as controller with Thread based devices please see How to use Thread based devices with matter.js Controller/Shell for more details.

We also collected some Troubleshooting information to help you with common issues.

A list ok known issues with some ecosystems can be found in KNOWN_ISSUES.md.

matter.js/matter-node.js as Controller was successfully tested with Chip example apps and several production devices (see here ).

Please report any outdated or newly discovered information on compatible ecosystems, devices, and device types or issues.

Monorepo Code structure Overview

This repository contains multiple packages (and because of this it is a monorepo). The packages are contained in the packages directory and are all published separately to NPM.

Please see the respective README files in the package directories for more information about their content.

For each package the API Documentation is updated on each official release, but can also be built locally using npm run build-doc.

Beside these packages that are published to npm there are also some packages that are not published to npm and exist as folders in the root directory:

This repository uses the workspaces feature from npm to manage the dependencies between the packages. Because of this please only use npm install on the root of the repository. This will install all the dependencies for all the packages and also take care to create relevant symlinks between the packages.

Additionally, it uses typescript project references to allow IDE support for the dependencies. These dependencies need to be added to the tsconfig.json files if needed.

You can build and test the packages separately or all by using npm run build or npm run test on root package level. With npm run build-clean you can build all packages from scratch.

Release tags

To allow a simple use of the matter.js Monorepo based project in other projects, we publish all packages separately to NPM. There are two available release tags on NPM:

Community communication

If you have issues please use the GitHub "Issues" of this repository. For questions or idea discussions please use the "Discussions" in this GitHub repository.

Additionally, we started a Discord server for Matter-Integrators to allow to communicate about the protocol and how to implement Matter in various environments (not only just JavaScript/Typescript). You can join it here: https://discord.gg/ujmRNrhDuW .

How to use matter.js

To develop matter.js

If you like to develop matter.js itself or want to contribute to it, you can use the following commands:

git clone https://github.com/project-chip/matter.js
cd matter.js
npm install

This will install all dependencies and create symlinks between the packages, so that it can be used locally. It also builds all packages.

On Windows in order to successfully build all the packages (tested on Windows 11 Pro) make sure that to have installed Node.js 18+, the windows-build-tools and node-gyp version 10. On Non-Windows platforms and having Python 3.12+ installed please also make sure to use npm 10.2.3+.

To use matter.js in your own project

To use matter.js you import @matter/main as dependency in your project. This package re-exports functionality from other packages, so it is not necessary to have multiple dependencies. If you need BLE support you can use @matter/nodejs-ble as additional dependency.

npm install @matter/main --save

If your project is not based on Node.js you need to implement the platform specific parts. See How to use matter.js in own projects for more details.

To try out the Node.js based Examples

if you just want to try out the examples on Node.js you can use the following commands:

npm install @matter/examples

Please refer to the Examples readme on how to use the examples: @matter/examples

Code style

matter.js relies very much on TypeScript and tries to be as type safe as possible. Please prevent using ts-ignore or other "hacks" as best as possible and try to find and fix the real typing issue if you encounter cases where you need to use them. YOu can also alwayys join discord or as in GitHub discussions if you need help.

The project contains eslint as linter and prettier as formatter. The configuration files are located in the root directory and are valid for all packages.

The following commands are available:

If you want to contribute to the project please make sure to check linting and formatting before creating a PR. The GitHub CI also verifies this and will fail if the code is not formatted correctly.

Building

You can use npm run build on the root level to build all packages in an incremental way. This will only build the changed files.

You can use npm run build-clean on the root level to build all packages from scratch.

Tests

You can use npm run test on the root level to run all tests for all packages.

Special testing using the Chip-Tool-Certification tests is available in the package matter-node.js-examples. Please refer to the README.md in the package for more details.

API documentation

You can use npm run build-doc on the root level to generate the API documentation for all packages in directory doc.

Current status

We are about to complete the basic certifiable feature set. Right now in the low level APIs all clusters are supported and all kind of devices can be built, but not with pre-defined cluster logic. See the Roadmap for status and next planned steps.

How to use matter.js in own projects

matter.js itself cannot be used directly in a project because some platform specific functionalities needs to be added. These are:

The following reference implementation and code references are available as basis for own platform implementations:

If you implement a specific platform we would be happy about a PR with the code, so that also other community members can benefit from it.

matter.js based projects

If you use a platform where Node.js 18+ is available then you can easily and directly use the following project that base on matter.js

matter.js is used at the core of those two projects currently: