Implementation of Matter protocol in Typescript with no native dependencies (and very limited dependencies).
Matter is a new secure / reliable / local / standard protocol for smart devices launched at the end of 2022. To know more about Matter: https://csa-iot.org/all-solutions/matter/
Devices created with matter.js/matter-node.js are compatible with:
- Apple iOS (iPhone or iPad) and tvOS 16 (Apple TV) - "Home" app by Apple: fully working
- Google Home Ecosystem (Android or Google Nest smart speakers/display) - "Google Home" app: fully working
- Amazon Alexa (Amazon Echo smart speakers/displays) : fully working
- Tuya Smart (SmartLife) app: fully working
- Samsung SmartThings (Station or Hub v2 and later): pairing works, but for controlling seems like Smartthings implementation itself has issues
- LG ThinQ: fully working
- Home Assistant - Matter integration: fully working
We also collected a list of known device types supported by which ecosystem.This is a compilation of published information and own community tests.
Each ecosystem have their own specialities, see Pairing and Usage Information for more details.
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 the following devices:
- Eve Energy (paired as secondary Controller via Apple Hub and also into own Thread network directly)
- TP-Link P-125M (US) Smart Plug (paired as secondary Controller via Apple Hub and also into own Wi-Fi network directly)
- Meross MSS115 (US) Smart Plug (paired as secondary Controller via Apple Hub and also into own Wi-Fi network directly)
- Chip-Tool
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.
- matter.js: the core Matter implementation in typescript which is JavaScript only and has no native dependencies.
- matter-node.js: a node.js implementation of a Matter DeviceNode and ControllerNode which also re-exports all matter.js exports and so can be used as only dependency
- matter-node-ble.js: a node.js based implementation of BLE features for matter-node.js to allow commissioning via BLE (Device and Controller)
- matter-node-shell.js: a node.js based Matter Shell script to allow to interact with Matter devices as controllers via a CLI interface
- matter-node.js-examples: Reference implementations of Matter devices and controller as CLI scripts using matter-node.js and matter-node-ble.js
For each package the API Documentation is updated on each release, but can be built locally using npm run build-doc.
This repository uses the workspaces feature on 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.
If you have issues please use the GitHub "Issues" feature of this repository. For questions or idea discussions please use the "Discussions" feature in GitHub.
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 .
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 installThis will install all dependencies and create symlinks between the packages, so that it can be used locally. It also builds all packages.
Matter.js is the core implementation of the Matter protocol in typescript. It is a JavaScript only implementation and has no native dependencies. It is build and published as CommonJS and ES6 variants in one package. For an overview of the exported functionality please refer to the README.md
Because Matter required UDP/MDNS technologies, other implementations are needed to implement this core functionality platform specific.
For more Details see the README.md in the package.
Matter-node.js uses Node.js to implement the platform specific parts using Node.js for networking and other needed native features. Additionally, it also implements a Matter DeviceNode and ControllerNode as a example implementation and allows to use this directly as CLI script. For an overview of the exported functionality please refer to the README.md
For more Details see the README.md in the package.
The project contains eslint as linter and typescript-formatter as formatter. The configuration files are located in the root directory and are valid for all packages.
The following commands are available:
npm run lint: runs eslint on all packages and outputs the results and errorsnpm run lint-fix: runs eslint on all packages and tries to fix the errorsnpm run format: runs typescript-formatter on all packages and formats the code. Files will be changed in place.npm run format-check: runs typescript-formatter on all packages and checks if the code is formatted correctly. If not it will output the files that need to be formatted.
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.
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.
You can use npm run build-doc on the root level to generate the API documentation for all packages in directory doc.
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 build, but not with pre-defined cluster logic. See the Roadmap for status and next planned steps.
matter.js itself can not be used directly in a project because some platform specific functionalities needs to be added. These are:
- BigInt/UInt8Array: Right now matter.js relies on certain ES6 JavaScript language features like BigInt and UInt8Array. If your platform does not support this you need to add a polyfill for this.
- Network: The Network implementation needs to provide UDP server and client functionality. This is a core requirement. The Network Interface needs to be implemented which includes methods to query network interfaces of the system and to use UDP sockets.
- Crypto: Until we have a pure JavaScript implementation of the required crypto functions, a native implementation is needed. The Crypto Interface needs to be implemented which includes methods to generate random numbers, generate keys and to encrypt/decrypt data with various algorithms.
- Storage: The Storage implementation needs to provide a way to store and retrieve data, easiest in a key-value form. The Storage Interface needs to be implemented which includes methods to store and retrieve data.
- Time: The Time implementation needs to provide a way to get the current time in milliseconds, but mainly need to offer Timer functionalities (Interval and Singe timers). The Time Interface needs to be implemented which includes methods to get the current time in milliseconds.
- BLE: If your implementation is not Ethernet based or Pre-Connected to an IP network you need to provide a BLE implementation. The BLE Interface needs to be implemented which includes methods to start and stop BLE advertising and to connect to a BLE device. Depending on if you implement a Controller or Device you need to implement the Peripheral and Broadcaster (Device) or Central and Scanner (Controller) BLE interfaces. For a device the platform you implement needs to allow to send custom "Manufacturer data" in the BLE advertising packet!
- Wi-Fi/Thread Commissioning: If you want to implement a Device which is not Ethernet based you need to provide a Wifi or Thread Commissioning implementation. This needs to include methods to scan for networks, configure the device for a network and to connect to a network. The implementation in this case needs to provide the functionality as command handlers for a WifiNetworkCommissioning- or a ThreadNetworkCommissioning-Cluster.
The following reference implementation and code references are available as basis for own platform implementations:
- For Network, Crypto, Storage and Time functionality you can use the Node.js implementations provided by matter-node.js as reference.
- For BLE functionality you can use the Node.js implementations provided by matter-node-ble.js as reference.
- For Wi-Fi/Thread Commissioning functionality you can use the Node.js DeviceNode example script which contains a static "testing only" (but API complete for Wifi) reference.
If you implement a specific platform we would be happy about aa PR with the code, so that also other community members can benefit from it.
If you use a platform where Node.js 16.x+ 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:
- matternode: a light-weight node.js implementation of a Matter Node
- matter-node.js: a Matter client / server running on node.js compatible with HA (Android / iOs support in progress)
- matter-node-shell.js: a Matter Shell script to allow to interact with Matter devices as controllers via a CLI interface
This list is a compilation of published information and own community tests. Many updates in the ecosystems happen without big announcements, so the information here can be a bit outdated and more device types are supported. If you find errors or added device types please open a PR or issue to report them. Especially for SmartThings and Tuya no information is officially published.
Table Legend:
- "X" means supported
- "-" means not supported from current knowledge
- "?" means unknown
| Device type | Apple | Amazon | SmartThings | LG ThinQ | Tuya | |
|---|---|---|---|---|---|---|
| Bridge Support | X | X | X | - | - | - |
| Light devices | ||||||
| * On/Off Light | X | X | X | X | X | X |
| * Dimmable Light | X | X | X | X | - | X |
| * Color Temperature Light | X | X | X | X | - | X |
| * Extended Color Light | X | X | X | ? | - | ? |
| Smart Plugs/Outlets/Actuators | ||||||
| * On/Off Plug-in Unit | X | X | X | X | X | X |
| * Dimmable Plug-in Unit | ? | ? | ? | ? | - | ? |
| * Pump | - | - | - | - | - | - |
| Sensors | ||||||
| * Contact Sensor | X | X | X | X | ? | ? |
| * Light Sensor | X | X | - | X | ? | ? |
| * Occupancy Sensor | X | X | - | ? | ? | ? |
| * Temperature Sensor | X | X | - | X | ? | ? |
| * Pressure Sensor | - | X | - | ? | ? | ? |
| * Flow Sensor | - | X | - | X | ? | ? |
| * Humidity Sensor | X | X | - | X | ? | ? |
| * On/Off Sensor | ? | ? | ? | ? | ? | ? |
| Closure Devices | ||||||
| * Door Lock | - | X | X | ? | ? | ? |
| * Window Covering | X | X (Lift only) | - | ? | ? | ? |
| HVAC Devices | ||||||
| * Heating/Cooling-Unit | - | - | - | - | ? | ? |
| * Thermostat | X | X | X | ? | ? | ? |
| * Fan | - | - | - | - | ? | ? |
| Media Devices | ||||||
| * Video Player Architecture | - | - | - | - | ? | - |
| * Basic Video Player | - | - | - | - | ? | - |
| * Casting Video Player | - | - | - | - | ? | - |
| * Speaker | X | - | - | ? | - | |
| * Content App | - | - | - | - | ? | - |
| Generic Devices | ||||||
| * Mode Select | - | - | X | - | ? | - |
It should work with any Matter-compatible home automation app when Matter will be released. We tested the Library with the "big" ones and can provide additional information.
A good guide with images on how to add devices to Alexa, Google and Apple in general is available in the TP-Link FAQ.
Minimum OS Required for iOS and tvOS devices: iOS 16.2 or later.
Apple support to set up HomePod, HomePod mini, Apple TV, or iPad (will not be supported anymore with the new Home Architecture starting iOS 16.3!) as a Matter Hub. The pairing itself can also be done using an iPhone, but the later controlling can only be done by one of the Hub options listed above!
When pairing with matter.js the Home app will ask you to allow to pair an "uncertified device" which you need to allow. After that the device will be added to the Home app, and you can control it from there.
We currently have no information which device types are supported by the Home app. But Lights and Sockets are support in any case.
Apple is using "two fabric IDs" on the paired devices (all others only use one). This needs to be considered when planning to pair devices with multiple controllers. How many fabrics are available depends on the device manufacturer (minimum are 3).
When removing a device paired with Apple Home only the main operational fabric from the two created ones is also removed. Additional pairings with e.g. Google Home or such should stay in tact. When no other pairing is active then the "System Commissioning fabric" (the second one created initially) needs to be removed manually via iOS: Settings - General - Matter-Devices!
Minimum Version Required for the "Google Home" app：2.62.1.15 or later.
Also for Google you need to have a Hub device (Android or Google Nest smart speakers/display) out of the list of supported devices to control your Matter devices.
Before you can pair matter.js to Google Home you need to allow uncertified devices for your Google Account. For this open the Google Developer Console to add an Integration and setup the device there. Please use 0xFFF1 as Vendor ID because matter.js uses this by the current scripts. If you do this that pairing will not be possible! If you have issues with pairing please refer to the Troubleshootling pages from Google.
Google supports several Matter device types already.
Minimum Version Required for the "Amazon Alexa" app：2.2.491118.0 or later.
For Amazon Alexa Usage you also need one Alexa device as Matter hub in your local network.
For Alexa no special setup is needed to pair with matter.js as development device.
The list of supported device types is basic currently, but will get enhanced in the future.
Alexa currently has a few non-standard requirements:
- Matter devices need to use port 5540 only (!), else they will not be discovered by Alexa at all
- The device needs to have an Endpoint 1 beside the root endpoint. This needs to either be the main device endpoint
- (composed devices not yet supported) or an aggregator.
Should work but no more detatailed information here as of yet.
Samsung is building its SmartThings hub software into 2022 Samsung Smart TVs, Smart Monitors, and Family Hub refrigerators, allowing them to control Matter smart home devices. Currently, Samsung SmartThings Station or Samsung SmartThings Hub v2 and later are needed as a hub for Matter.
- Samsung "Samsung SmartThings Station" does support Matter devices over LAN, Wi-Fi, and over Thread radio (Thread Border Router).
- "Aeotec Smart Home Hub" (rebranded Samsung SmartThings Hub v3) will be getting an update to supports Matter over Wi-Fi.
- "Samsung SmartThings Hub v3" (ETH-ETH-300 from 2018) has been updated to support Matter over Wi-Fi.
- "Samsung SmartThings Hub v2" (ETH-ETH-250 from 2016) has been updated to support Matter over Wi-Fi.
- "Samsung SmartThings Hub v2" (ETH-ETH-200 from 2015) has been updated to support Matter over Wi-Fi.
- "SmartThings Family Hub" smart fridge might or might not get updated to support Matter at a later date.
- "SmartThings Hub v1" (F-H-ETH-001 and STH-ETH-001) has been discontinued and will not get updated to support Matter.
- "Samsung SmartThings Link" (USB dongle) for Nvidia Shield has been discontinued and will not get updated to support Matter.
Note! Samsung has started that they do not plan on bridging Zigbee and Z-Wave devices connected to their hubs with Matter (e.i. no protocol bridge so far).
Home Assistant's official Matter integration is in Beta-stage however it is fully working and compatible with the Matter 1.0 standard. To connect Thread based devices you also need an Thread Border Router radio that is compatible with Home Assistant's official Thread integration, that includes their official Home Assistant Yellow hub and their Home Assistant SkyConnect Zigbee/Thread USB dongle.
- https://www.home-assistant.io/integrations/matter/
- https://www.home-assistant.io/integrations/thread/
Compile chip-tool from project-chip
Provisioning the device:
chip-tool pairing onnetwork 222 20202021
Controlling the device:
chip-tool onoff toggle 222 1
Clearing the data:
chip-tool pairing unpair 222
and/or
chip-tool storage clear-all
You can also control it with Matter test app: https://github.com/project-chip/connectedhomeip/tree/master/src/android/CHIPTest You can find a compiled apk in /matter-test-apk in this repository.
Provisioning the device: click "provision with WiFi" > "Input DeviceNode address" > type IP address of the machine running matter.js
Controlling the device: click "Light on/of" and you can control the light
Well, the original codebase is platform dependent, has finicky tool version requirements and is over 8GB with all dependencies. This tool is less than 500kB and works on anything supporting node. Sure, it supports only the barebone Matter protocol for now.
Not yet, but I know how to make it works with a few tricks.
Adding more clusters should be pretty easy now the core protocol is working. Have a look at the implementation of the OnOff cluster: pretty simple, right?
I am planning on adding more clusters, so stay tuned or pinged me to implement first the one you need.
For other questions, you can post a message on the github forum, open an issue, or join Discord https://discord.gg/ujmRNrhDuW .