DOCSEARCHbyAlgolia
Submit Docs

matter.js

repository·main·Indexed 21 days ago

https://github.com/matter-js/matter.js

A complete TypeScript/JavaScript implementation of the Matter smart home protocol. It enables the development of Matter-compatible devices, bridges, and controllers, and includes a Matter Shell for testing. The library consists of core modules (@project-chip/matter.js), Node.js specific implementations (@project-chip/matter-node.js), and BLE modules for Node.js (@project-chip/matter-node-ble.js). Note: matter.js and its examples are not CSA certified and are intended for development and testing.

Tokens
241.7K
Snippets
647
Records
1.4K
Agent score
75%

What's inside matter.js

  1. Use Matter.js Code Generation scripts

    main

    The @matter/codegen package provides a collection of scripts designed to support code generation and analysis for the matter.js codebase. These tools are used to automate the creation of code based on the Matter.js model definitions.

    For specific instructions on how to use the code generation features, how the models are structured, and how to generate code from them, refer to the matter.js model README located at packages/model/README.md.

  2. Security Warning for @matter/nodejs-shell

    main

    ⚠️ Development and testing tool only.

    The shell and its optional WebSocket/web interface are intended for development, testing, and debugging. They are not hardened for production use because:

    • They have no authentication.
    • Credentials are stored unencrypted on disk.
    • The WebSocket/web interface serves the shell without access control.

    Do not expose this shell on untrusted networks or run it as a production service.

  3. Use @matter/thread-br-client for Thread Border Router communication

    main

    @matter/thread-br-client provides tools for communicating with Thread Border Routers (BR). It enables mDNS discovery of BRs, decoding of Thread Operational Datasets, and querying network diagnostics via either an OpenThread REST API (OTBR) or MeshCoP (CoAP over DTLS-EC-JPAKE).

    Key Capabilities:

    • Discovery: Passive mDNS discovery of Border Routers using BorderRouterRegistry.
    • Dataset Management: Decoding and encoding of Thread Operational Datasets using OperationalDataset.
    • Diagnostics (OTBR REST): Accessing node info, network diagnostics, and active-dataset via OtbrRestClient and OtbrRestDiagnosticSource.
    • Diagnostics (MeshCoP): Commissioner-style diagnostic queries via connectMeshcop and MeshCopDiagnosticSource.

    Note on Runtime: The package is portable and runs in Node.js, browsers, and React-Native because it uses the matter.js Crypto abstraction instead of Node-specific dependencies.

  4. Important note on matter.js certification

    main

    The matter.js library, its related tools (such as the Shell app), and all examples are not certified by the Connectivity Standards Alliance (CSA). They are provided for demonstration, testing, and development purposes only.

    Using matter.js does not certify your product. To release official Matter devices, you must obtain Connectivity Standards Alliance membership and undergo formal product certification.

  5. Explore matter.js-based projects and implementations

    main

    The matter.js ecosystem includes various implementations for clients, servers, bridges, and controllers. These projects are compatible with any platform running Node.js 20+.

    Key Implementations:

    • Node.js Clients/Servers:

      • @matter/nodejs: A Matter client/server running on Node.js, compatible with Home Assistant (Android/iOS support in progress).
      • @matter/nodejs-shell: A Matter Shell script providing a CLI interface to interact with Matter devices as a controller.

    • Bridges and Adapters:

      • ioBroker Matter Adapter: An open-source smart home system for Matter Devices, Bridges, and Controllers.
      • node-red-matter-bridge: A Node-Red node used to expose a bridge.
      • zigbee-matter-bridge: A bridge that converts Zigbee to Matter.
      • matterbridge: A plugin manager for matter.js with various plugins (e.g., matterbridge-zigbee2mqtt, matterbridge-shelly, matterbridge-somfy-tahoma) to expose existing ecosystems to Matter.
      • Home Assistant Matter Hub: Exposes Home Assistant entities as Matter devices to controllers like Apple Home, Google Home, Alexa, and SmartThings.
      • Matter Bridge for Homey Pro: A bridge implementation for Homey Pro.

    • Controllers and Assistants:

      • Gladys Assistant: An open-source smart home assistant that uses matter.js as a controller.
      • matter-controller: Web-based examples of Matter Controllers that communicate with the Matter Shell via web sockets.

  6. Understand the Simple light controller example

    main

    The control-onoff example demonstrates a basic Matter controller. In the Matter ecosystem, a controller is a device capable of performing commissioning—the process of adding new devices to a Matter network.

    This specific example implements a controller that can:

    1. Commission a new device into the network.
    2. Interact with devices that support the on/off cluster.
    3. Toggle the state (on/off) of those devices.

  7. Access matter.js API documentation

    main

    The matter.js API documentation is organized by package and is updated with every release. You can find the full documentation at the hosted site: https://matter-js.github.io/docs/.

    Key documentation sections include:

    • @project-chip/matter.js: Core modules and main API information.
    • @project-chip/matter-node.js: Node.js specific implementation modules.
    • @project-chip/matter-node-ble.js: Bluetooth Low Energy (BLE) specific modules for Node.js.

    For detailed device information, refer to the matter.js/API.md file within the repository.

  8. How to use Thread-based devices with matter.js

    main

    Thread is a low-power, wireless mesh networking protocol used by Matter devices. To connect Thread devices to an operational IP-based network, a Thread Border Router (TBR) is required. The TBR facilitates IPv6 communication between the Thread network and your local IP network.

    Key Concepts

    • Thread Border Router (TBR): A device (like a smart hub or a Raspberry Pi with a USB stick) that bridges Thread networks to the internet/local IP network.
    • Shared Thread Network: For maximum efficiency, all Matter devices should ideally reside on the same Thread network to allow direct communication without round-tripping through the TBR.
    • IPv6 Requirements: If using existing ecosystems (Apple, Google, Amazon) as TBRs, ensure your host or VM has a proper IPv6 setup configured.

  9. Important certification notice for matter.js

    main

    It is critical to note that matter.js, including its libraries, tools (like the Shell app), and examples, is not certified by the Connectivity Standards Alliance (CSA).

    • matter.js is provided solely for demonstrating capabilities and supporting testing and development.
    • Using matter.js does not certify your product.
    • To release official Matter devices, you must obtain Connectivity Standards Alliance membership and undergo formal product certification.

  10. Use the matter.js CHIP container

    main

    The ghcr.io/matter-js/chip container provides a pre-configured environment containing chip-tool and connectedhomeip certification tests.

    Important Requirements:

    • The container requires host networking.
    • The container requires access to a local Avahi instance for MDNS.

    If you are using the matter.js test harness, this image is pulled automatically when running CHIP tests.

  11. When to use @matter/node

    main

    The @matter/node package provides Matter-specific functionality tailored for Node.js environments.

    Important: For most standard use cases, you should not use this package directly. Instead, import the main matter.js package. @matter/node is intended only for special cases where Node-specific implementation details are required.

  12. Use @matter/main as a single-dependency package

    main

    @matter/main is a TypeScript implementation of the Matter protocol designed to be a convenient single-dependency for applications. It provides automatic registrations for Node.js and React Native platforms.

    Compatibility Note: When using Node.js, this package supports all LTS versions starting from 20.x.

    Abstraction Model: To allow for environment-specific implementations, the following core functionalities are abstracted away and must be provided or configured for your specific environment:

    • Network (UDP/MDNS)
    • Crypto
    • Storage
    • Date/Timer
    • Logger (defaults to console)
    • Environment (Process and Configuration handling)