Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/luligu/matterbridge
Matterbridge plugin manager for Matter
https://github.com/luligu/matterbridge
alexa bridge connectedthings google-home homeassistant homekit iot matter matterbridge matterprotocol plugin siri smarthome somfy tahoma zigbee zigbee2mqtt
Last synced: 1 day ago
JSON representation
Matterbridge plugin manager for Matter
- Host: GitHub
- URL: https://github.com/luligu/matterbridge
- Owner: Luligu
- License: apache-2.0
- Created: 2024-02-22T10:04:26.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-12-15T14:59:30.000Z (7 days ago)
- Last Synced: 2024-12-15T15:57:52.493Z (7 days ago)
- Topics: alexa, bridge, connectedthings, google-home, homeassistant, homekit, iot, matter, matterbridge, matterprotocol, plugin, siri, smarthome, somfy, tahoma, zigbee, zigbee2mqtt
- Language: TypeScript
- Homepage: https://github.com/Luligu/matterbridge/blob/main/README.md
- Size: 26.7 MB
- Stars: 288
- Watchers: 10
- Forks: 27
- Open Issues: 3
-
Metadata Files:
- Readme: README-DEV.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# 
Matterbridge
[](https://www.npmjs.com/package/matterbridge)
[](https://www.npmjs.com/package/matterbridge)
[](https://hub.docker.com/r/luligu/matterbridge)
[](https://hub.docker.com/r/luligu/matterbridge)
[](https://www.npmjs.com/package/matter-history)
[](https://www.npmjs.com/package/node-ansi-logger)
[](https://www.npmjs.com/package/node-persist-manager)
---
# Development
## Guidelines on imports/exports
Matterbridge exports from:
"matterbridge"
- Matterbridge and all Matterbridge related classes.
- All relevant matter-node.js or matter.js clusters, classes and functions.
"matterbridge/matter"
- All relevant matter.js new api only exports (in beta).
"matterbridge/cluster"
- All clusters not present in matter.js or modified.
"matterbridge/utils"
- All general utils and colorUtils functions.
"matterbridge/logger"
- AnsiLogger class.
"matterbridge/storage"
- NodeStorageManager and NodeStorage classes.
# \***\*\*\*\*\***
A plugin must never install or import from `@matter` or `@project-chip` directly (neither as a dependency, devDependency, nor peerDependency), as this leads to a second instance of `matter.js`, causing instability and unpredictable errors such as "The only instance is Endpoint".
Additionally, when Matterbridge updates the `matter.js` version, it should be consistent across all plugins.
# \***\*\*\*\*\***
A plugin must never install Matterbridge (neither as a dependency, devDependency, nor peerDependency).
Matterbridge must be linked to the plugin in development only.
```json
"scripts": {
'''
"dev:link": "npm link matterbridge",
'''
}
```
# \***\*\*\*\*\***
I added some error messages when a plugin has wrong imports or configurations and the plugin will be disabled to prevent instability and crashes.
## Migration to matter.js V8
I'm working with matter.js team to define the strategy for the migration of Matterbridge to the new API.
- First phase: create MatterbridgeEdge class: completed 95%
- Second phase: create MatterbridgeEndpoint and MatterbridgeBehaviors classes: completed 95%
- Third phase: modifiy all plugins to support both normal and edge mode of Matterbridge: completed 90%
- Fourth phase: remove all old api code from Matterbridge and all plugins...
## How to create your plugin
The easiest way is to clone:
- https://github.com/Luligu/matterbridge-example-accessory-platform if you want to create an Accessory Platform Plugin.
- https://github.com/Luligu/matterbridge-example-dynamic-platform if you want to create a Dynamic Platform Plugin.
Then change the name (keep matterbridge- at the beginning of the name), version, description and author in the package.json.
Add your plugin logic in platform.ts.
## How to install and register a plugin for development (from github)
To install i.e. https://github.com/Luligu/matterbridge-example-accessory-platform
On windows:
```
cd $HOME\Matterbridge
```
On linux:
```
cd ~/Matterbridge
```
then clone the plugin
```
git clone https://github.com/Luligu/matterbridge-example-accessory-platform
cd matterbridge-example-accessory-platform
npm install
npm run build
```
then add the plugin to Matterbridge
```
matterbridge -add .\
```
## MatterbridgeDynamicPlatform and MatterbridgeAccessoryPlatform api
### public name: string
The plugin name.
### public type: string
The plugin platform type.
### public config: object
The plugin config (loaded before the platform constructor is called and saved after onShutdown() is called).
Here you can store your plugin configuration (see matterbridge-zigbee2mqtt for example)
### async onStart(reason?: string)
The method onStart() is where you have to create your MatterbridgeDevice and add all needed clusters and command handlers.
The MatterbridgeDevice class has the create cluster methods already done and all command handlers needed (see plugin examples).
The method is called when Matterbridge load the plugin.
### async onConfigure()
The method onConfigure() is where you can configure or initialize your device.
The method is called when the platform is commissioned.
### async onShutdown(reason?: string)
The method onShutdown() is where you have to eventually cleanup some resources.
The method is called when Matterbridge is shutting down.
### async registerDevice(device: MatterbridgeDevice)
After you created your device, add it to the platform.
### async unregisterDevice(device: MatterbridgeDevice)
You can unregister one or more device.
### async unregisterAllDevices()
You can unregister all devices you added.
It can be useful to call this method from onShutdown() if you don't want to keep all the devices during development.
## MatterbridgeDevice api
Work in progress...
# Contribution Guidelines
Thank you for your interest in contributing to my project!
I warmly welcome contributions to this project! Whether it's reporting bugs, proposing new features, updating documentation, or writing code, your help is greatly appreciated.
## Getting Started
- Fork this repository to your own GitHub account and clone it to your local device.
- Make the necessary changes and test them out
- Commit your changes and push to your forked repository
## Submitting Changes
- Create a new pull request against the dev from my repository and I'll be glad to check it out
- Be sure to follow the existing code style
- Add unit tests for any new or changed functionality if possible
- In your pull request, do describe what your changes do and how they work