matterbridge 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project will be documented in this file.
 
 If you like this project and find it useful, please consider giving it a star on GitHub at https://github.com/Luligu/matterbridge and sponsoring it.
 
+## [1.5.0] - 2024-08-27
+
+### Breaking Changes
+
+- [-bridge -childbridge]: You don't need anymore to add the parmeter -bridge or -childbridge on the command line or systemctl configuration or docker command: the default is bridge mode and if no parameter is added, Matterbridge uses the settings from the frontend that are saved.
+- [-logger]: You don't need anymore to add the parmeter -logger [level]: the default is info and if no parameter is added, Matterbridge uses the settings from the frontend that are saved.
+- [-filelogger]: You don't need anymore to add the parmeter -filelogger: the default is false and if no parameter is added, Matterbridge uses the settings from the frontend that are saved.
+- [-matterlogger]: You don't need anymore to add the parmeter -matterlogger [level]: the default is info and if no parameter is added, Matterbridge uses the settings from the frontend that are saved.
+- [-matterfilelogger]: You don't need anymore to add the parmeter -matterfilelogger: the default is false and if no parameter is added, Matterbridge uses the settings from the frontend that are saved.
+
+### Breaking Changes for developers
+
+- please read this [Development guide lines](https://github.com/Luligu/matterbridge/blob/main/README-DEV.md)
+
+### Added
+
+- [frontend]: Added menu item "Update".
+- [frontend]: Added menu item "Restart".
+- [frontend]: Added menu item "Shutdown".
+- [frontend]: Added menu item "Download".
+- [frontend]: Added menu item "Backup".
+- [frontend]: Added menu item "Unregister all devices" with a confirmation dialog.
+- [frontend]: Added menu item "Reset commissioning" with a confirmation dialog.
+- [frontend]: Added menu item "Factory reset" with a confirmation dialog.
+
+### Changed
+
+- [package]: Update dependencies.
+
+<a href="https://www.buymeacoffee.com/luligugithub">
+  <img src="./yellow-button.png" alt="Buy me a coffee" width="120">
+</a>
+
 ## [1.4.3] - 2024-08-22
 
 ### Added

package/README-ADVANCED.md

@@ -0,0 +1,197 @@
+# <img src="https://github.com/Luligu/matterbridge/blob/main/frontend/public/matterbridge%2064x64.png" alt="Matterbridge Logo" width="64px" height="64px">&nbsp;&nbsp;&nbsp;Matterbridge
+
+[![npm version](https://img.shields.io/npm/v/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![npm downloads](https://img.shields.io/npm/dt/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge?label=docker%20version&sort=semver)](https://hub.docker.com/r/luligu/matterbridge)
+[![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge.svg)](https://hub.docker.com/r/luligu/matterbridge)
+![Node.js CI](https://github.com/Luligu/matterbridge/actions/workflows/build.yml/badge.svg)
+
+[![power by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
+[![power by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)
+[![power by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](https://www.npmjs.com/package/node-persist-manager)
+
+---
+
+# Advanced configuration
+
+## Run matterbridge as a daemon with systemctl (Linux only)
+
+Create a systemctl configuration file for Matterbridge
+
+```
+sudo nano /etc/systemd/system/matterbridge.service
+```
+
+Add the following to this file, replacing twice (!) USER with your user name (e.g. WorkingDirectory=/home/pi/Matterbridge and User=pi):
+
+You may need to adapt the configuration to your setup:
+ - execStart on some linux distribution can also be ExecStart==/usr/bin/matterbridge -service
+
+```
+[Unit]
+Description=matterbridge
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=matterbridge -service
+WorkingDirectory=/home/<USER>/Matterbridge
+StandardOutput=inherit
+StandardError=inherit
+Restart=always
+RestartSec=10s
+TimeoutStopSec=30s
+User=<USER>
+
+[Install]
+WantedBy=multi-user.target
+```
+
+If you modify it after, then run:
+
+```
+sudo systemctl daemon-reload
+```
+
+### Start Matterbridge
+
+```
+sudo systemctl start matterbridge
+```
+
+### Stop Matterbridge
+
+```
+sudo systemctl stop matterbridge
+```
+
+### Show Matterbridge status
+
+```
+sudo systemctl status matterbridge.service
+```
+
+### View the log of Matterbridge in real time (this will show the log with colors)
+
+```
+sudo journalctl -u matterbridge.service -f --output cat
+```
+
+### Delete the logs older then 3 days (all of them not only the ones of Matterbridge!)
+
+```
+sudo journalctl --vacuum-time=3d
+```
+
+### Enable Matterbridge to start automatically on boot
+
+```
+sudo systemctl enable matterbridge.service
+```
+
+### Disable Matterbridge from starting automatically on boot
+
+```
+sudo systemctl disable matterbridge.service
+```
+
+## Run matterbridge with docker
+
+The Matterbridge Docker image, which includes a manifest list for the linux/amd64, linux/arm64 and linux/arm/v7 architectures, is published on Docker Hub.
+
+### First create the Matterbridge directories
+
+This will create the required directories if they don't exist
+
+```
+cd ~
+mkdir -p ./Matterbridge
+mkdir -p ./.matterbridge
+sudo chown -R $USER:$USER ./Matterbridge ./.matterbridge
+```
+You may need to adapt the script to your setup.
+
+### Run the Docker container and start it
+
+The container has full access to the host network (needed for mdns).
+
+```
+docker run --name matterbridge \
+  -v ${HOME}/Matterbridge:/root/Matterbridge \
+  -v ${HOME}/.matterbridge:/root/.matterbridge \
+  --network host --restart always -d luligu/matterbridge:latest
+```
+You may need to adapt the script to your setup.
+
+### Run with docker compose
+
+The docker-compose.yml file is available in the docker directory of the package
+
+```
+services:
+  matterbridge:
+    container_name: matterbridge
+    image: luligu/matterbridge:latest # Matterbridge image with the latest tag
+    network_mode: host # Ensures the Matter mdns works
+    restart: always # Ensures the container always restarts automatically
+    volumes:
+      - "${HOME}/Matterbridge:/root/Matterbridge" # Mounts the Matterbridge plugin directory
+      - "${HOME}/.matterbridge:/root/.matterbridge" # Mounts the Matterbridge storage directory
+```
+
+copy it in the home directory or edit the existing one to add the matterbridge service.
+
+Then start docker compose with:
+
+```
+docker compose up -d
+```
+
+### Stop with docker compose
+
+```
+docker compose down
+```
+
+### Update with docker compose
+
+```
+docker compose pull
+```
+
+### Inspect the container
+
+```
+docker container inspect matterbridge
+```
+
+### Start the Docker container
+
+```
+docker start matterbridge
+```
+
+### Stop the Docker container
+
+```
+docker stop matterbridge
+```
+
+### Restart the Docker container
+
+```
+docker restart matterbridge
+```
+
+### Shows the logs
+
+```
+docker logs matterbridge
+```
+
+### Shows the logs real time (tail)
+
+```
+docker logs --tail 1000 -f matterbridge
+```
+

package/README-DEV.md

@@ -0,0 +1,167 @@
+# <img src="https://github.com/Luligu/matterbridge/blob/main/frontend/public/matterbridge%2064x64.png" alt="Matterbridge Logo" width="64px" height="64px">&nbsp;&nbsp;&nbsp;Matterbridge
+
+[![npm version](https://img.shields.io/npm/v/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![npm downloads](https://img.shields.io/npm/dt/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge?label=docker%20version&sort=semver)](https://hub.docker.com/r/luligu/matterbridge)
+[![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge.svg)](https://hub.docker.com/r/luligu/matterbridge)
+![Node.js CI](https://github.com/Luligu/matterbridge/actions/workflows/build.yml/badge.svg)
+
+[![power by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
+[![power by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)
+[![power by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](https://www.npmjs.com/package/node-persist-manager)
+
+---
+
+# Development
+
+## Guidelines on imports/exports
+
+Matterbridge export from:
+
+"matterbridge"
+- Matterbridge and MatterbridgeDevice class.
+- All relevant matter-node.js or matter.js classes and functions.
+
+"matterbridge/cluster"
+- All clusters not present in matter.js or modified.
+
+"matterbridge/utils"
+- All general utils and colorUtils functions.
+
+"matterbridge/history"
+- MatterHistory class.
+
+"matterbridge/logger"
+- NodeAnsiLogger class.
+
+"matterbridge/storage"
+- NodeStorage classes.
+
+# **********
+A plugin will never ever install and import from matter-node.js or matter.js directly cause this leads to a second instance of matter.js that causes instability and unpredictable errors like "The only instance is Enpoint". 
+
+In the next releases I will remove the duplicated exports so please update your plugins.
+
+I will also add some error messages when a plugin has wrong imports.
+# **********
+
+## Guidelines on the 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.
+
+More informations will be added soon.
+
+## 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