Live loading of external JS (#3229)

docs/advanced/more/external_converters.md

@@ -0,0 +1,74 @@
+---
+sidebar: auto
+---
+
+# External converters
+
+Zigbee2MQTT uses [zigbee-herdsman-converters](https://github.com/Koenkk/zigbee-herdsman-converters) to parse messages to and from devices.
+
+External converters provide a way to test support for new devices, they work identically to internal converters.
+
+External converters are stored in `data/external_converters` folder and have to export a JavaScript Object or Array of Object matching the type [`DefinitionWithExtend`](https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/lib/types.ts). Refer to [existing converters](https://github.com/Koenkk/zigbee-herdsman-converters/tree/master/src/devices) to get familiar with the framework.
+
+:::tip TIP
+Once your converter is ready, open a [pull request](https://github.com/Koenkk/zigbee-herdsman-converters/pulls) so it can be integrated into Zigbee2MQTT for all to use. Once the new Zigbee2MQTT version is released, you can just delete the external converter.
+:::
+
+Example:
+
+File: `data/external_converters/my-first-converter.js`
+
+```js
+const {temperature, humidity, battery} = require('zigbee-herdsman-converters/lib/modernExtend');
+
+const definition = {
+    zigbeeModel: ['lumi.sens'],
+    model: 'WSDCGQ01LM',
+    vendor: 'Xiaomi',
+    description: 'MiJia temperature & humidity sensor',
+    extend: [temperature(), humidity(), battery()],
+};
+
+module.exports = definition;
+```
+
+### More examples
+
+-   [Sensor using modern extends](https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/sensor_me.js) (same as above)
+-   [Sensor using non modern extends](https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/sensor.js)
+-   [Bulb (light)](https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/light.js)
+-   [Plug (switch)](https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/switch.js)
+-   [Advanced example](https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/freepad_ext.js)
+-   Definitions of already supported devices can be found [here](https://github.com/Koenkk/zigbee-herdsman-converters/tree/master/src/devices). It may help to look at devices from the same vendor or type.
+
+### Using modern extends
+
+The entire API can be found [here](https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/lib/modernExtend.ts).
+
+### Using non modern extends
+
+The most common API endpoints are accessible from the following imports:
+
+```js
+const fz = require('zigbee-herdsman-converters/converters/fromZigbee');
+const tz = require('zigbee-herdsman-converters/converters/toZigbee');
+const exposes = require('zigbee-herdsman-converters/lib/exposes');
+const reporting = require('zigbee-herdsman-converters/lib/reporting');
+const ota = require('zigbee-herdsman-converters/lib/ota');
+const utils = require('zigbee-herdsman-converters/lib/utils');
+const globalStore = require('zigbee-herdsman-converters/lib/store');
+const e = exposes.presets;
+const ea = exposes.access;
+```
+
+## Converters list
+
+When Zigbee2MQTT starts it publishes `zigbee2mqtt/bridge/converters` with payload `[{"name": "my-first-converter.js": "code": <HERE COMES YOUR CONVERTER CODE>}]` containing all the converters loaded from the file system. The same message is also published when a converter changes at runtime (from one of the below actions), with the appropriately updated payload.
+
+## Save converter
+
+To save a converter at runtime, send a message to `zigbee2mqtt/bridge/request/converter/save` with payload `{"name": "my-first-converter.js", "code": <HERE COMES YOUR CONVERTER CODE>}`. The code will be saved in `data/external_converters/` in the file with the given name.
+
+## Remove converter
+
+To remove a converter at runtime, send a message to `zigbee2mqtt/bridge/request/converter/remove` with payload `{"name": "my-first-converter.js"}`. The file will be deleted from `data/external_converters/`.

docs/advanced/more/external_extensions.md

@@ -0,0 +1,66 @@
+---
+sidebar: auto
+---
+
+# External extensions
+
+External extensions provide a way to extend Zigbee2MQTT behavior, they work identically to internal extensions.
+
+To get familiar with the Extension framework, refer to the [source code of internal extensions](https://github.com/Koenkk/zigbee2mqtt/tree/master/lib/extension).
+
+External extensions are stored in `data/external_extensions` folder and have to export a JavaScript Class that conforms to the `Extension` base class (see above link).
+
+Example:
+
+File: `data/external_extensions/my-first-extension.js`
+
+```js
+class MyExampleExtension {
+    constructor(zigbee, mqtt, state, publishEntityState, eventBus, settings, logger) {
+        this.zigbee = zigbee;
+        this.mqtt = mqtt;
+        this.state = state;
+        this.publishEntityState = publishEntityState;
+        this.eventBus = eventBus;
+        this.settings = settings;
+        this.logger = logger;
+
+        logger.info('Loaded  MyExampleExtension');
+    }
+
+    /**
+     * Called when the extension starts (on Zigbee2MQTT startup, or when the extension is saved at runtime)
+     */
+    start() {
+        this.mqtt.publish('example/extension', 'hello from MyExampleExtension');
+
+        // All possible events can be seen here: https://github.com/Koenkk/zigbee2mqtt/blob/master/lib/eventBus.ts
+
+        // Subscribe to MQTT messages
+        this.eventBus.onMQTTMessage(this, (data) => {
+            console.log(`Received MQTT message on topic '${data.topic}' with message '${data.message}'`);
+        });
+    }
+
+    /**
+     * Called when the extension stops (on Zigbee2MQTT shutdown, or when the extension is saved/removed at runtime)
+     */
+    stop() {
+        this.eventBus.removeListeners(this);
+    }
+}
+
+module.exports = MyExampleExtension;
+```
+
+## Extensions list
+
+When Zigbee2MQTT starts it publishes `zigbee2mqtt/bridge/extensions` with payload `[{"name": "my-first-extension.js": "code": <HERE COMES YOUR EXTENSION SOURCE CODE>}]` containing all the extensions loaded from the file system. The same message is also published when an extension changes at runtime (from one of the below actions), with the appropriately updated payload.
+
+## Save extension
+
+To save an extension at runtime, send a message to `zigbee2mqtt/bridge/request/extension/save` with payload `{"name": "my-first-extension.js", "code": <HERE COMES YOUR EXTENSION SOURCE CODE>}`. The code will be saved in `data/external_extensions/` in the file with the given name.
+
+## Remove extension
+
+To remove an extension at runtime, send a message to `zigbee2mqtt/bridge/request/extension/remove` with payload `{"name": "my-first-extension.js"}`. The file will be deleted from `data/external_extensions/`.