feat: Configurator to generate basic configuration.yaml (#3413)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

docs/.vuepress/components/Configurator.vue

@@ -0,0 +1,202 @@
+<template lang="pug">
+div.configurator
+  label(for="mqttServer") Address of your MQTT server
+  input(v-model="mqttServerKey" id="mqttServer" type="text")
+  label(for="adapterPathType") Connectivity of your adapter
+  select(v-model="adapterPathTypeKey" id="adapterPathType")
+    option(value="Serial" selected) Serial (USB)
+    option(value="TCP") TCP
+  label(for="adapterPath") Path of your adapter
+  input(v-model="adapterPathKey" id="adapterPath" type="text")
+  label(for="adapterType") Type of your adapter
+  select(v-model="adapterTypeKey" id="adapterType")
+    option(value="zstack" selected) zstack
+    option(value="ember") ember
+    option(value="deconz") deconz
+    option(value="zigate") zigate
+    option(value="zboss") zboss
+  label(for="wifiChannel") Channel of closest WiFi 2.4GHz network
+  input(v-model="wifiChannelKey" id="wifiChannel" type="number" min=1 max=14 step=1)
+  label(for="frontend" class="checkbox")
+    input(v-model="frontendKey" id="frontend" type="checkbox" checked)
+    .
+      Enable frontend?
+  label(for="homeAssistant" class="checkbox")
+    input(v-model="homeAssistantKey" id="homeAssistant" type="checkbox")
+    .
+      Enable Home Assistant integration?
+  p() Configuration:
+  textarea(v-model="configurationKey" rows=16 disabled)
+</template>
+
+<script lang="ts">
+import {defineComponent, ref, SetupContext, watch} from 'vue';
+
+/**
+ * Very basic algorithm to get farthest away from the WiFi channel while remaining on "preferred" ZigBee channels (11, 15, 20, 25)
+ */
+function bestZigbeeChannel(wifiChannel: number) {
+    if (wifiChannel >= 11) {
+        // WiFi 11-14
+        return 15;
+    } else if (wifiChannel >= 6) {
+        // WiFi 6-10
+        return 11;
+    } else {
+        // WiFi 1-5
+        return 25;
+    }
+}
+
+export default defineComponent({
+    name: 'Configurator',
+    setup(props, ctx: SetupContext) {
+        // ctx.attrs: {mqtt: string; portType: 'Serial' | 'TCP'; serial: string; tcp: string;}
+        const defaultMQTTServer = ctx.attrs.mqtt ? ctx.attrs.mqtt : 'mqtt://<IP_ADDRESS>:<PORT>';
+        const defaultSerialPath = ctx.attrs.serial ? ctx.attrs.serial : '/dev/serial/by-id/<SERIAL_ID>';
+        const defaultPortType = ctx.attrs.portType === 'TCP' ? 'TCP' : 'Serial';
+        const defaultTCPPath = ctx.attrs.tcp ? ctx.attrs.tcp : 'tcp://<IP_ADDRESS>:<PORT>';
+        const defaultAdapter = ctx.attrs.adapter ? ctx.attrs.adapter : 'zstack';
+
+        const mqttServerKey = ref('');
+        const adapterPathTypeKey = ref('');
+        const adapterPathKey = ref('');
+        const adapterTypeKey = ref('');
+        const wifiChannelKey = ref('');
+        const frontendKey = ref('');
+        const homeAssistantKey = ref('');
+        const configurationKey = ref('');
+
+        watch(
+            adapterPathTypeKey,
+            (adapterPathType) => {
+                if (!adapterPathType || adapterPathType === 'Serial') {
+                    adapterPathTypeKey.value = 'Serial';
+                    adapterPathKey.value = defaultSerialPath;
+                } else {
+                    adapterPathTypeKey.value = 'TCP';
+                    adapterPathKey.value = defaultTCPPath;
+                }
+            },
+            {immediate: true},
+        );
+
+        watch(
+            [mqttServerKey, adapterPathKey, adapterTypeKey, wifiChannelKey, frontendKey, homeAssistantKey],
+            ([mqttServer, adapterPath, adapterType, wifiChannel, frontend, homeAssistant]) => {
+                if (!mqttServer) {
+                    mqttServer = defaultMQTTServer;
+                    mqttServerKey.value = defaultMQTTServer;
+                }
+
+                if (!adapterPath) {
+                    if (adapterPathType === 'TCP') {
+                        adapterPath = defaultTCPPath;
+                        adapterPathKey.value = defaultTCPPath;
+                    } else {
+                        adapterPath = defaultSerialPath;
+                        adapterPathKey.value = defaultSerialPath;
+                    }
+                }
+
+                if (!adapterType) {
+                    adapterType = defaultAdapter;
+                    adapterTypeKey.value = defaultAdapter;
+                }
+
+                if (!wifiChannel) {
+                    wifiChannel = 6;
+                    wifiChannelKey.value = 6;
+                }
+
+                if (typeof frontendKey.value !== 'boolean') {
+                    frontend = true;
+                    frontendKey.value = true;
+                }
+
+                if (typeof homeAssistantKey.value !== 'boolean') {
+                    homeAssistant = false;
+                    homeAssistantKey.value = false;
+                }
+
+                // XXX: version should be kept in sync with Z2M's (updated with every release)
+                configurationKey.value = `
+version: 4
+mqtt:
+    base_topic: zigbee2mqtt
+    server: ${mqttServer}
+serial:
+    port: ${adapterPath}
+    adapter: ${adapterType}
+advanced:
+    channel: ${bestZigbeeChannel(wifiChannel)}
+    network_key: GENERATE
+    pan_id: GENERATE
+    ext_pan_id: GENERATE
+frontend:
+    enabled: ${frontend}
+homeassistant:
+    enabled: ${homeAssistant}
+`.trim();
+            },
+            {immediate: true},
+        );
+
+        return {
+            mqttServerKey,
+            adapterPathTypeKey,
+            adapterPathKey,
+            adapterTypeKey,
+            wifiChannelKey,
+            frontendKey,
+            homeAssistantKey,
+            configurationKey,
+        };
+    },
+});
+</script>
+
+<style lang="scss">
+.configurator {
+    margin-top: 1rem;
+    padding: 1rem 1rem;
+    border: 1px solid #333;
+    border-radius: 0.3rem;
+
+    label {
+        display: block;
+        width: 100%;
+    }
+
+    input,
+    select,
+    textarea {
+        display: inline-flex;
+        font-size: 1rem;
+        max-width: 100%;
+        width: 100%;
+        margin-top: 0.4rem;
+        margin-bottom: 0.8rem;
+        padding: 0.2rem 0.4rem;
+        box-sizing: border-box;
+    }
+
+    input:not([type='checkbox']),
+    select {
+        height: 2rem;
+        line-height: 1.5;
+    }
+
+    input[type='checkbox'] {
+        height: 1rem;
+        line-height: 1;
+    }
+
+    label.checkbox {
+        input {
+            width: auto;
+            vertical-align: baseline;
+        }
+    }
+}
+</style>

docs/guide/configuration/zigbee-network.md

@@ -4,19 +4,6 @@ sidebarDepth: 1
 
 # Zigbee network
 
-## Permit join
-
-```yaml
-# Optional: allow new devices to join.
-permit_join: true
-```
-
-::: warning ATTENTION
-It's important to disable `permit_join` after you've peered your devices. This keeps the Zigbee
-network safe and prevents accidental joining of other Zigbee devices. When a device joins, the coordinator exposes the
-network key.
-:::
-
 ## Network config
 
 ```yaml
@@ -43,6 +30,10 @@ Set `network_key: GENERATE` to let Zigbee2MQTT generate a new random key on the
 [Reduce Wi-Fi interference by changing the Zigbee channel](../../advanced/zigbee/02_improve_network_range_and_stability.md#reduce-wi-fi-interference-by-changing-the-zigbee-channel)
 :::
 
+### Configurator
+
+<Configurator />
+
 ### Changing the Zigbee channel
 
 Changing the channel of an existing Zigbee network is supported. In Zigbee, this is done by broadcasting a network update indicating the channel change. Devices that are asleep during the broadcast (usually battery powered end devices) will not switch immediately, but the next time they wake-up. It is therefore advised to trigger them after the channel change.

docs/guide/getting-started/README.md

@@ -64,6 +64,8 @@ Zigbee2MQTT supports mDNS autodiscovery feature for network Zigbee adapters. If
 
 ### 2.) Setup and start Zigbee2MQTT
 
+#### 2.1) Configure Docker
+
 It's assumed, that you have a recent version of Docker and Docker Compose installed.
 
 First, we create a folder where we want the project to reside `mkdir folder-name`. In the folder, we create we save the `docker-compose.yml` file which defines how Docker would run our containers. The following file consists of two services, one for the MQTT-Server and one for Zigbee2MQTT itself. Be sure to adjust the file to your needs and match the devices-mount in the case your adapter was not mounted on `/dev/ttyUSB0` or in case you use a network adapter.
@@ -96,27 +98,15 @@ services:
             - /dev/ttyUSB0:/dev/ttyUSB0
 ```
 
+#### 2.2) Configure Zigbee2MQTT
+
 In the next step we'll create a simple [Zigbee2MQTT config file](../configuration/) in `zigbee2mqtt-data/configuration.yaml`.
 
-```yaml
-# Let new devices join our zigbee network
-permit_join: true
-# Docker Compose makes the MQTT-Server available using "mqtt" hostname
-mqtt:
-    base_topic: zigbee2mqtt
-    server: mqtt://mqtt
-# Zigbee Adapter path
-serial:
-    port: /dev/ttyUSB0
-# Enable the Zigbee2MQTT frontend
-frontend:
-    port: 8080
-# Let Zigbee2MQTT generate a new network key on first start
-advanced:
-    network_key: GENERATE
-```
+NOTE: Docker Compose makes the MQTT-Server available using "mqtt" hostname.
+
+<Configurator mqtt="mqtt://mqtt" serial="/dev/ttyUSB0" portType="Serial" adapter="zstack" />
 
-For network adapters, `serial` settings should look like this:
+For network adapters, `serial` > `port` settings should look like this:
 
 ```yaml
 serial:
@@ -134,6 +124,8 @@ serial:
 
 Where `slzb-06` is the mDNS name of your network Zigbee adapter.
 
+#### 2.3) Start Zigbee2MQTT
+
 We should now have two files in our directory and can start the stack:
 
 ```bash