How matter-js/matterjs-server works
This repository provides a matter.js-based Matter controller server with a Python-compatible WebSocket API, plus client libraries and a browser dashboard. The main workflow is a Home Assistant or other client connecting over WebSocket, issuing commissioning or device commands, and receiving node and network updates. The server also supports configuration persistence, OTA uploads, custom clusters, and optional BLE proxying. Relationships among packages are documented in the README; source excerpts and the index clarify selected controller internals, but do not establish every runtime connection.
Main entry points: MatterServer.ts Matter Server · MatterController.ts Matter Controller · WebSocketControllerHandler.ts WebSocket API · ControllerCommandHandler.ts Device Commands
Components 18
Server and API
- Matter Server
packages/matter-server/src/MatterServer.ts - WebSocket API
packages/ws-controller/src/server/WebSocketControllerHandler.ts - Configuration Storage
packages/ws-controller/src/server/ConfigStorage.ts - OTA Upload
packages/matter-server/src/server/OtaUploadHandler.ts
Matter Controller
- Matter Controller
packages/ws-controller/src/controller/MatterController.ts - Device Commands
packages/ws-controller/src/controller/ControllerCommandHandler.ts - Node Processing
packages/ws-controller/src/controller/NodeProcessor.ts - Network Topology
packages/ws-controller/src/controller/NetworkTopologyService.ts - Thread Diagnostics
packages/ws-controller/src/controller/ThreadDiagnosticsService.ts
Clients and Dashboard
- WebSocket Client
packages/ws-client/src/client.ts - Dashboard
packages/dashboard/src/pages/matter-dashboard-app.ts
Extensions
- BLE Proxy
packages/ble-proxy/src/BleProxyHandler.ts - Custom Clusters
packages/custom-clusters/src/clusters/aqara.ts
Python Support
- Python Client
python_client/matter_server/client/client.py - Python Cluster Models
python_client/chip/clusters/ClusterObjects.py - TLV Codec
python_client/chip/tlv/__init__.py
Other components
- Home Assistant
- Other API Client
Connections 19
- Home Assistant → Matter Server: connects to
README.md - Other API Client → Matter Server: connects to
README.md - Matter Server → Matter Controller: uses controller
README.md - Matter Server → WebSocket API: serves API
README.md - Matter Controller → Configuration Storage: uses storage
packages/ws-controller/src/controller/MatterController.ts - WebSocket API → Matter Controller: routes requests
packages/ws-controller/src/server/WebSocketControllerHandler.ts - WebSocket API → Device Commands: dispatches commands
packages/ws-controller/src/server/WebSocketControllerHandler.ts - Matter Controller → Device Commands: creates handler
packages/ws-controller/src/controller/MatterController.ts - Device Commands → Node Processing: uses node processing
packages/ws-controller/src/controller/ControllerCommandHandler.ts - Matter Controller → Network Topology: uses topology service
packages/ws-controller/src/controller/MatterController.ts - Matter Controller → Thread Diagnostics: uses diagnostics
packages/ws-controller/src/controller/MatterController.ts - WebSocket Client → WebSocket API: communicates over WebSocket
README.md - Dashboard → WebSocket Client: uses client library
- Matter Server → OTA Upload: provides upload
README.md - Matter Server → BLE Proxy: optionally exposes proxy
README.md - Matter Server → Custom Clusters: uses cluster extensions
README.md - Python Client → Matter Server: connects by WebSocket
README.md - Python Client → Python Cluster Models: uses cluster models
python_client/matter_server/client/client.py - Python Cluster Models → TLV Codec: serializes data
python_client/chip/clusters/ClusterObjects.py