This plugin allows you to expose all Shelly Gen 1, Gen 2, Gen 3 and BLU devices to Matter.
Features:
If you like this project and find it useful, please consider giving it a star on GitHub at https://github.com/Luligu/matterbridge-shelly and sponsoring it.
This project is proudly sponsored by:
I would like to express my appreciation to Tamer Salah for his invaluable contribution to this project. His expertise and assistance have been instrumental in its success. You can sponsor Tamer here https://buymeacoffee.com/6sjde6vkzl.
Follow these steps to install or update Matterbridge if it is not already installed and up to date:
npm install -g matterbridge
on Linux you may need the necessary permissions:
sudo npm install -g matterbridge
See the complete guidelines on Matterbridge for more information.
A shelly device gen. 1 or 2 or 3 or BLU.
For Gen. 1 devices:
For wifi battery-powered devices:
Gen. 1: only for the first time, when you want to register them: check that enableMdnsDiscover and enableStorageDiscover are flagged in the plugin configuration. Restart matterbridge (the mdns discovery is active for the first 10 minutes) and awake each device you want to register pressing the device button.
Gen. 2/3: in the device web page go to "Settings", then "Outbound websocket" and enable it, select "TLS no validation" and put in the server field "ws://matterbridge-ipv4:8485" (e.g. ws://192.168.1.100:8485). You can find the matterbridge ipv4Address address in the frontend or in the log. Then, only for the first time, when you want to register them: check that enableMdnsDiscover and enableStorageDiscover are flagged in the plugin configuration. Restart matterbridge (the mdns discovery is active for the first 10 minutes) and awake each device you want to register pressing the device button.
For BLU devices:
Just open the frontend, select the matterbridge-shelly plugin and click on install. If you are using Matterbridge with Docker (I suggest you do it), all plugins are already loaded in the container so you just need to select and add it.
On windows:
cd $HOME\Matterbridge
npm install -g matterbridge-shelly
matterbridge -add matterbridge-shelly
On linux:
cd ~/Matterbridge
sudo npm install -g matterbridge-shelly
matterbridge -add matterbridge-shelly
Then start Matterbridge from a terminal
matterbridge
You may need to set some config values in the frontend:
If your devices are password protected put there the username. It must be unique for all the devices. It is only used for gen 1 devices. Gen 2 and 3 devices have always admin.
If your devices are password protected put there the password. It must be unique for all the devices.
Choose how to expose the shelly switches: as a switch (don't use it with Alexa), light or outlet.
Choose how to expose the shelly inputs: disabled, contact, momentary or latching switch (default disabled)
Choose how to expose the shelly input events: momentary switch or disabled (default disabled)
Choose how to expose the shelly power meters: disabled, matter13 (it uses Matter 1.3 electricalSensor device type still not supported by any controller) or evehistory (it uses the Matter EveHistoryCluster that is supported only by Home Assistant)
If the blackList is defined the devices included in the list will not be exposed to Matter. Use the device id (e.g. shellyplus2pm-5443B23D81F8)
If the whiteList is defined only the devices included in the list are exposed to Matter. Use the device id (e.g. shellyplus2pm-5443B23D81F8).
You can put there one of more of your devices if they have problem with mdns (don't use it unless is needed). E.g. "shelly1minig3-543204547478": "192.168.1.221"
Should always be enabled to discover new devices. It turns off automatically after 10 minutes to reduce network traffic. Once a device is discovered, it is added to the shelly storage.
Should always be enabled to automatically add all the devices previously discovered.
Reset the storage discovery on the next restart (it will clear the storage of already discovered devices).
Should be enabled only if the mdns is not working in your network. It adds the devices defined in deviceIp.
Should be enabled to discover the shelly BLU devices (it will register the BLU devices paired in each ble gateway, see https://github.com/Luligu/matterbridge-shelly/blob/dev/BLU.md for more informations).
Should be enabled only if you want to debug some issue using the log.
Should be enabled only if you want to debug some issue with mdns using the log.
Should be enabled only if you want to debug some issue with CoIoT using the log.
Should be enabled only if you want to debug some issue with the WebSocket client or server using the log.
Should be enabled only if you want to remove the devices from the controllers on shutdown.
These are the config values:
{
"name": "matterbridge-shelly",
"type": "DynamicPlatform",
"username": "<USERNAME>",
"password": "<PASSWORD>",
"exposeSwitch": "switch" | "light" | "outlet"
"exposeInput": "disabled" | "contact" | "momentary" | "latching"
"exposeInputEvent": "disabled" | "momentary"
"blackList": [],
"whiteList": [],
"deviceIp": {
"<DEVICEID1>": "x.x.x.x",
"<DEVICEID2>": "x.x.x.x"
},
"enableMdnsDiscover": true,
"enableStorageDiscover": true,
"resetStorageDiscover": false
"enableConfigDiscover": false,
"debug": false,
"debugMdns": false,
"debugCoap": false,
"debugWs": false,
"interfaceName": ""
"unregisterOnShutdown": false,
}
You can edit the config file from the frontend (best option) or
On windows:
cd $HOME\.matterbridge
notepad matterbridge-shelly.config.json
On linux:
cd ~/.matterbridge
nano matterbridge-shelly.config.json
Restart Matterbridge for the changes to take effect.