This library supports reading and controlling Shelly devices.
The library communicates with Shelly devices by REST api (for controlling) and the CoAP protocol with the default Shelly firmware (no flashing of firmware needed!). Because CoAP use multicast UDP packages, the Shelly devices has to be in the same subnet like the host you use the library on. If you use them in a docker container, the container has to run in host or macvlan modus.
The library provides an event driven interface to inform you about status updates that are received using COAP packages.
tbd
Constructor to init the object. In options you can provide:
- "logger" to be used for debug logging.
- "user" and "password" for Shelly devices with authentication activated. It is assumed that all devices use same credentials
Starts listening for CoAP packages in the network. Callback is called without parameters after listening started.
Stops listening for CoAP package. Callback is provided for convenience and called synchron without parameters.
Sends a multicast package so that all devices should answer with a status package. Callback is provided for convenience and called synchron without parameters.
Contacts a known device by Device-ID or by IP to request the device description. Callback is called with the following parameters: error, deviceId, payload, deviceIp
Contacts a known device by Device-ID or by IP to request the device status update. Callback is called with the following parameters: error, deviceId, payload, deviceIp
You can provide an array of Device-IDs or IP to request status updates. They will be emitted as events once received.
Sends a REST call to a known device by Device-ID or by IP to a certain path with parameters. The result is returned as callback. Callback is called with the following parameters: error, response data
If an error happens while parsing the received data an error event is emitted. Listening will continue, so it is no "fatal error"!
Emits connection status information for a device. A device is considered "offline" when no status update is received longer then the defined timeframe. Parameters are: deviceId and connection-status true/false
Emits device status update information for a device. Parameters are: deviceId and status payload
Emitted when listener disconnects, normally when you call stopListening()
The library also offers a index-dummy.js which offers the same interface then the real library and emits and provides example data.
- Shelly1 (SHSW-1, Verified)
- Shelly2 (SHSW-21/SHSW-22, Verified)
- ShellyPlug (SHPLG-1, Verified)
- Shelly4Pro (SHSW-44, Reading works, Controlling not verified)
- Shelly Sense (SHSEN-1, Reading not verified)
- ShellyBulb (SHBLB-1, reading some data may work, no control)
- Shelly2LED (SH2LED-1, reading some data may work, no control)
- ShellyRGBW (SHRGBWW-01, reading some data may work, no control)
- add example code
- add proper deep testing (maybe using mock-dgram?)
- more detailed docs?
- add error handling for CoAP requests
- also emit device status update when IP has changed
- check if payload is identical. Work around for Shelly H&T with equal serial numbers in messages with new payload
- fix online flag, finally
- fix online flag
- add option to also handle password protected shelly devices on REST calls
- small fix for better online status handling
- initial version