Troubleshooting information added for UPnP (Issue #13077) (#2190)

* Troubleshooting information added for UPnP (Issue #13077) Additional technical information related to UPnP device discovery added (required for bindings that use the UPnP infrastructure of openHAB). Signed-off-by: Patrik Gfeller <[email protected]> * markdownlint findings fixed. Signed-off-by: Patrik Gfeller <[email protected]> * erros fixed (found in generated doc pre-view) Signed-off-by: Patrik Gfeller <[email protected]> * Add support for footnotes to markdown parser. Signed-off-by: Patrik Gfeller <[email protected]> * Change stylus code to place the footer at the very end of the page ... Signed-off-by: Patrik Gfeller <[email protected]> * Update styles to improve footnote placement. Signed-off-by: Patrik Gfeller <[email protected]> * Additional footnote styling. * Information about parameter "-Dorg.jupnp.network.useAddresses" added. Clarified that openHAB uses the jupnp library for UPnP support. Signed-off-by: Patrik Gfeller <[email protected]> * linter findigs fixed ... Signed-off-by: Patrik Gfeller <[email protected]> * small re-wording Signed-off-by: Patrik Gfeller <[email protected]> * Rollback of changes that do not belong to this PR * [Enancement] - Simplify local builds to lower bar for beginners Fixes #2215 - resolved comments by @stefan-hoehn - added more information to USB section, as in my expirience to use the device id is more reliable the host system configuration changes. --------- Signed-off-by: Patrik Gfeller <[email protected]>
openhab · Feb 5, 2024 · 1025a02 · 1025a02
1 parent ac78eb1
commit 1025a02
Showing 1 changed file with 114 additions and 1 deletion.
diff --git a/installation/docker.md b/installation/docker.md
@@ -253,9 +253,96 @@ It then performs all the same steps that the upgrade script and which are perfor
 
 ## Troubleshooting
 
+### Universal Plug and Play (UPnP)
+
+Some bindings, like e.g. [SONOS](https://www.openhab.org/addons/bindings/sonos/), depend on the common [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play) communication infrastructure installed with openHAB.
+The protocol is based on IP multicast messages, which are limited to a local subnet.
+In case you have multiple network adapters in your system (which is the case if you use docker), it is necessary to inform openHAB what interface shall be used for UPnP discovery and communication.
+If more than one IP address is assigend to the interface, the address to use must be specified as well.
+
+This information can be specified via the `EXTRA_JAVA_OPTS` [Environment Variable](#environment-variables):
+
+```bash
+EXTRA_JAVA_OPTS="-Dorg.jupnp.network.useInterfaces=eno1 -Dorg.jupnp.network.useAddresses=192.168.0.65"
+```
+
+:::: tabs
+
+::: tab Linux
+
+::: tip Note
+To get full advantage of a docker/container setup it is recommended to learn about [docker compose](https://docs.docker.com/compose/).
+The following example is using docker compose syntax.
+:::
+
+Identify the network interface on the host machine:
+
+```bash
+> ip --brief address show
+lo               UNKNOWN        127.0.0.1/8 ::1/128 
+eno1             UP             192.168.0.65/24  
+eno1.4@eno1      UP             192.168.6.97/24  
+docker0          DOWN           172.17.0.1/16  
+br-7406c5aa57f0  UP             172.25.0.1/16  
+```
+
+.env
+
+```ini
+COMPOSE_PROJECT_NAME=openhab
+
+OPENHAB_ADDONS=/opt/openhab/addons
+OPENHAB_CONF=/opt/openhab/conf
+OPENHAB_LOGDIR=/opt/openhab/userdata/logs
+OPENHAB_USERDATA=/opt/openhab/userdata
+
+EXTRA_JAVA_OPTS="-Duser.timezone=Europe/Berlin -Dorg.jupnp.network.useInterfaces=eno1 -Dorg.jupnp.network.useAddresses=192.168.0.65"
+```
+
+docker-compose.yaml:
+
+```yaml
+version: '3.9'
+services:
+
+  frontail:     # place frontail configuration here ... 
+  grafana:      # place grafana configuration here ...
+  influxdb:     # place influx configuration here ...
+  zigbee2mqtt:  # place zigbee2mqtt configuration here ..
+  mosquitto:    # place mosquitto configuration here ...
+
+  openhab:
+    depends_on:
+      - frontail
+      - influxdb
+      - grafana
+      - zigbee2mqtt
+    container_name: ${COMPOSE_PROJECT_NAME}-server
+    image: openhab/openhab:4.1.0-debian
+    restart: unless-stopped
+    network_mode: host
+    group_add:
+      - tty
+    volumes:
+      - /etc/localtime:/etc/localtime
+      - /etc/timezone:/etc/timezone
+      - $OPENHAB_CONF/ssh:/openhab/.ssh
+      - $OPENHAB_ADDONS:/openhab/addons
+      - $OPENHAB_CONF:/openhab/conf
+      - $OPENHAB_USERDATA:/openhab/userdata
+    devices:
+      - /dev/serial/by-id/usb-0658_0200-if00:/dev/ttyACM2
+      - /dev/serial/by-id/usb-Prolific_Technology_Inc._USB-Serial_Controller_D-if00-port0:/dev/ttyUSB0
+    environment:
+      - CRYPTO_POLICY=unlimited
+      - EXTRA_JAVA_OPTS=${EXTRA_JAVA_OPTS} 
+```
+
+::::
+
 ### USB sticks
 
-If you want use an USB stick (for example for Z-Wave network), then it will be not available for the dockerized system by default.
+USB periferals (for example for Z-Wave, or ZigBee network sticks) will not be available by default to the dockerized system.
 In Docker openHAB is running in name of `openhab`, a restricted user.
 The stick will work if you run the following command right after Docker image is started.
 
@@ -289,4 +376,30 @@ This command changes permissions of the specific device as expected (readable an
 
 ::: tip Note
 The device path (`/dev/ttyACM0`) or container name (`openhab`) could be different in your system, command can be modified accordingly.
+Instead of using e.g. `/dev/ttyACM0` to identify the device it might be more robust to identify a device by id (e.g. if you add devices, plug in the stick in a different port):
+
+```yml
+devices:
+  - /dev/serial/by-id/usb-0658_0200-if00:/dev/ttyACM2
+  - /dev/serial/by-id/usb-Prolific_Technology_Inc._USB-Serial_Controller_D-if00-port0:/dev/ttyUSB0
+```
+
+How to identify the device:
+
+```bash
+> pwd
+/dev/serial/by-id
+
+> ls -l
+total 0
+lrwxrwxrwx 1 root root 13 Jan 19 17:26 usb-0658_0200-if00 -> ../../ttyACM0
+lrwxrwxrwx 1 root root 13 Jan 19 17:26 usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_20220810144536-if00 -> ../../ttyACM1
+lrwxrwxrwx 1 root root 13 Jan 19 17:26 usb-Prolific_Technology_Inc._USB-Serial_Controller_D-if00-port0 -> ../../ttyUSB0
+
+> lsusb
+Bus 002 Device 003: ID 067b:2303 Prolific Technology, Inc. PL2303 Serial Port / Mobile Action MA-8910P
+Bus 002 Device 007: ID 1a86:55d4 QinHeng Electronics SONOFF Zigbee 3.0 USB Dongle Plus V2
+Bus 002 Device 004: ID 0658:0200 Sigma Designs, Inc. Aeotec Z-Stick Gen5 (ZW090) - UZB
+```
+
 :::