-
-
Notifications
You must be signed in to change notification settings - Fork 213
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: plugins improved support (#688)
With this PR users will have more power when developing custom plugins. More info in [docs](https://zwave-js.github.io/zwavejs2mqtt/#/guide/plugins) BREAKING CHANGE: `plugins` are now stored in an array of `strings` on settings `gateway` prop instead of `zwave`
- Loading branch information
1 parent
5a43abd
commit a213b25
Showing
7 changed files
with
108 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
# Plugins | ||
|
||
Plugins are nodejs packages that can be integrated in zwavejsmqtt in order to add new awesome features. They have access to all the clients (zwave and mqtt) and express instance. | ||
|
||
## Usage | ||
|
||
A plugin is imported in zwavejs1mqtt using `require(pluginName)(context)` where context provides access to these elements: | ||
|
||
- `zwave`: Zwave client | ||
- `mqtt`: Mqtt client | ||
- `app`: Express instance | ||
- `logger`: A logger instance to log things in console/file based on logger general settings | ||
|
||
In order to add a plugin you have to specify the absolute/relative path to it or, if it is available as an npm package, you can install it using the command: | ||
|
||
```bash | ||
npm i my-awesome-plugin | ||
``` | ||
|
||
## Plugins with docker | ||
|
||
Building the container is straight forward. Here an example of build command installing plugin `my-awesome-plugin` | ||
|
||
```bash | ||
docker build -f docker/Dockerfile --build-arg plugins='my-awesome-plugin' -t <docker image name>:<tag> . | ||
``` | ||
|
||
## Developing custom Plugins | ||
|
||
In order to implement a plugin you need to create a class with a constructor that accepts a single parameter that is the context we spoke in [usage](#usage) section and a `destroy` function that will be called when application is closed or settings updated. | ||
|
||
Here is a minimal example of a custom plugin: | ||
|
||
```js | ||
function MyPlugin (ctx) { | ||
this.zwave = ctx.zwave | ||
this.mqtt = ctx.mqtt | ||
this.logger = ctx.logger | ||
this.express = ctx.app | ||
|
||
// this.express.get('/my-route', function(req, res) {...}) | ||
// this.mqtt.publish(...) | ||
// this.zwave.on('valueChanged', onValueChanged) | ||
// ... add all the stuff you need here | ||
} | ||
|
||
MyPlugin.prototype.destroy = async function () { | ||
// clean up the state | ||
} | ||
|
||
module.export = MyPlugin | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters