feat: plugins improved support

app.js

@@ -89,6 +89,7 @@ socketManager.authMiddleware = function (socket, next) {
 }
 
 let gw // the gateway instance
+const plugins = []
 
 // flag used to prevent multiple restarts while one is already in progress
 let restarting = false
@@ -249,9 +250,41 @@ function startGateway (settings) {
 
   gw.start()
 
+  const pluginsConfig = settings.gateway ? settings.gateway.plugins : null
+
+  // load custom plugins
+  if (pluginsConfig && Array.isArray(pluginsConfig)) {
+    for (const plugin of pluginsConfig) {
+      try {
+        const pluginName = path.basename(plugin)
+        const instance = require(plugin)({
+          zwave,
+          mqtt,
+          app,
+          logger: loggers.module(pluginName)
+        })
+        instance.name = pluginName
+        plugins.push(instance)
+        logger.info(`Successfully loaded plugin ${instance.name}`)
+      } catch (error) {
+        logger.error(`Error while loading ${plugin} plugin`, error)
+      }
+    }
+  }
+
   restarting = false
 }
 
+async function destroyPlugins () {
+  while (plugins.length > 0) {
+    const instance = plugins.pop()
+    if (instance && typeof instance.destroy === 'function') {
+      logger.info('Closing plugin ' + instance.name)
+      await instance.destroy()
+    }
+  }
+}
+
 function setupInterceptor () {
   // intercept logs and redirect them to socket
   const interceptor = function (write) {
@@ -806,6 +839,7 @@ app.post('/api/settings', apisLimiter, isAuthenticated, async function (
     restarting = true
     await jsonStore.put(store.settings, settings)
     await gw.close()
+    await destroyPlugins()
     // reload loggers settings
     setupLogging(settings)
     // restart clients and gateway
@@ -849,6 +883,7 @@ async function gracefuShutdown () {
   logger.warn('Shutdown detected: closing clients...')
   try {
     await gw.close()
+    await destroyPlugins()
   } catch (error) {
     logger.error('Error while closing clients', error)
   }

docs/_sidebar.md

@@ -20,6 +20,7 @@
   - [Z2M Migration](guide/migrating.md)
   - [Env Vars](guide/env-vars.md)
   - [FAQ](guide/faq.md)
+  - [Plugins](guide/plugins.md)
 
 - Development
 

docs/guide/plugins.md

@@ -0,0 +1,52 @@
+# Plugins
+
+Plugins are nodejs packages that can be initegrated 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)(contex)` where context provides access to this 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
+```

lib/ZwaveClient.js

@@ -114,15 +114,6 @@ function ZwaveClient (config, socket) {
   this.healTimeout = null
 
   this.status = ZWAVE_STATUS.closed
-
-  // load custom plugins
-  if (config.plugin) {
-    try {
-      require(config.plugin)(this)
-    } catch (error) {
-      logger.error(`Error while loading ${config.plugin} plugin`, error.message)
-    }
-  }
 }
 
 inherits(ZwaveClient, EventEmitter)

src/components/Settings.vue

@@ -25,6 +25,18 @@
                           v-model="newGateway.authEnabled"
                         ></v-switch>
                       </v-col>
+                      <v-col cols="12" sm="6" md="4">
+                        <v-combobox
+                          hint="You can select a plugin from the list or write the path to your custom plugin and press enter"
+                          persistent-hint
+                          label="Plugins"
+                          :items="['@varet/zj2m-prom-exporter']"
+                          multiple
+                          chips
+                          deletable-chips
+                          v-model="newGateway.plugins"
+                        ></v-combobox>
+                      </v-col>
                       <v-col cols="12" sm="6" md="4">
                         <v-switch
                           hint="Enable logging"

src/store/mutations.js

@@ -28,6 +28,8 @@ export const state = {
   devices: [],
   gateway: {
     type: 0,
+    plugins: [],
+    authEnabled: false,
     payloadType: 0,
     nodeNames: true,
     hassDiscovery: true,