Add support for addon_configs to zwave_js

zwave_js/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0
+
+### Features
+
+- Add-On: Provide access to Z-Wave JS cache files for debugging in `/addon_configs/core_zwave_js/cache`
+- Add-On: Add configuration option to log to file. When enabled, logs will be written to `/addon_configs/core_zwave_js` with the `.log` file extension
+
 ## 0.3.0
 
 ### Features

zwave_js/DOCS.md

@@ -138,7 +138,18 @@ This option sets the log level of Z-Wave JS. Valid options are:
 If no `log_level` is specified, the log level will be set to the level set in
 the Supervisor.
 
-### Option `soft_reset`
+### Option `log_to_file` (optional)
+
+When this option is enabled, logs will be written to the `/addon_configs/core_zwave_js`
+folder with the `.log` file extension.
+
+### Option `log_max_files` (optional)
+
+When `log_to_file` is true, Z-Wave JS will create a log file for each
+day. This option allows you to control the maximum number of files that
+Z-Wave JS will keep.
+
+### Option `soft_reset` (optional)
 
 This setting tells the add-on how to handle soft-resets for 500 series controllers:
 1. Automatic - the add-on will decide whether soft-reset should be enabled or disabled for 500 series controllers. This is the default option and should work for most people.
@@ -176,6 +187,17 @@ the introduction of S2 security inclusion in zwave-js, this option has been
 deprecated in favor of `s0_legacy_key`. If still set, the `network_key` value will be
 migrated to `s0_legacy_key` on first startup.
 
+### Troubleshooting network issues
+
+There are several features available in the add-on that can help you in troubleshooting network issues and/or providing data to either the Home Assistant or Z-Wave JS team to help in tracing an issue:
+
+1. **Update the log level:** It is extremely helpful when opening a GitHub issue to set the `log_level` configuration option to `debug` and capture when the issue occurs.
+2. **Log to file:** The `log_to_file` and `log_max_files` configuration options allow you to enable and configure that. Note that in order to access the log files, you will need to be able to access the filesystem of your HA instance, which you can do with the file editor, samba, or ssh add-ons among others.
+3. **Access Z-Wave JS cache:** Z-Wave JS stores information it discovers about your network in cache files so that your devices don't have to be reinterviewed on every startup. In some cases, when opening a GitHub issue, you may be asked to provide the cache files. You can access them in `/addon_configs/core_zwave_js/cache`. Note that in order to access the cache, you will need to be able to access the filesystem of your HA instance, which you can do with the file editor, samba, or ssh add-ons among others.
+4. **Change soft reset behavior:** By default, the addon will choose whether or not to soft reset the controller at startup automatically. In most cases that shouldn't be changed, but if asked to make a change when troubleshooting an issue, you can do so using the `soft_reset` configuration option.
+5. **Disable controller recovery:** By default, if the network controller appears to be jammed, Z-Wave JS will automatically try to restore the controller to a healthy state. In most cases that shouldn't be changed, but if asked to make a change when troubleshooting an issue, you can do so using the `disable_controller_recovery` configuration option.
+6. **Enable safe mode:** When Z-Wave JS is having trouble starting up, it can sometimes be hard to get useful logs to troubleshoot the issue. By setting `safe_mode` to true, Z-Wave JS may be able to start up in cases where it wouldn't with the `safe_mode` set to false. Note that enabling `safe_mode` will have a negative impact on the performance of your network and should be used sparingly.
+
 ## Known issues and limitations
 
 - Your hardware needs to be compatible with the Z-Wave JS library

zwave_js/config.yaml

@@ -1,5 +1,5 @@
 ---
-version: 0.3.0
+version: 0.4.0
 slug: zwave_js
 name: Z-Wave JS
 description: Control a Z-Wave network with Home Assistant Z-Wave JS
@@ -17,9 +17,13 @@ hassio_api: true
 homeassistant: 2021.2.0b0
 image: homeassistant/{arch}-addon-zwave_js
 init: false
+map:
+  - addon_config:rw
 options:
   device: null
   log_level: info
+  log_to_file: false
+  log_max_files: 7
   soft_reset: Automatic
   s0_legacy_key: ""
   s2_access_control_key: ""
@@ -30,6 +34,8 @@ ports:
 schema:
   device: device(subsystem=tty)
   log_level: list(silly|debug|verbose|http|info|warn|error)?
+  log_to_file: bool?
+  log_max_files: int(1,)?
   soft_reset: list(Automatic|Enabled|Disabled)?
   s0_legacy_key: match(|[0-9a-fA-F]{32,32})?
   s2_access_control_key: match(|[0-9a-fA-F]{32,32})?

zwave_js/rootfs/etc/cont-init.d/config.sh

@@ -145,13 +145,18 @@ else
     presets="$(printf '%s\n' "${presets_array[@]}" | jq -R . | jq -s .)"
 fi
 
+log_to_file=$(bashio::config "log_to_file")
+log_max_files=$(bashio::config "log_max_files")
+
 # Generate config
 bashio::var.json \
     s0_legacy "${s0_legacy}" \
     s2_access_control "${s2_access_control}" \
     s2_authenticated "${s2_authenticated}" \
     s2_unauthenticated "${s2_unauthenticated}" \
     log_level "${log_level}" \
+    log_to_file "${log_to_file}" \
+    log_max_files "${log_max_files}" \
     soft_reset "^${soft_reset}" \
     presets "${presets}" |
     tempio \

zwave_js/rootfs/etc/cont-init.d/structure.sh

@@ -2,5 +2,13 @@
 # ==============================================================================
 # Setup folder structure
 # ==============================================================================
-mkdir -p /data/cache
 mkdir -p /data/db
+
+if bashio::fs.directory_exists '/data/cache'; then
+    bashio::log.info "Migrating 'cache' folder from private storage to /addon_configs/core_zwave_js"
+    mv /data/cache /config/cache
+fi
+
+if ! bashio::fs.directory_exists '/config/cache'; then
+    mkdir -p /config/cache
+fi

zwave_js/rootfs/usr/share/tempio/zwave_config.conf

@@ -2,10 +2,13 @@
     "logConfig": {
         "enabled": true,
         "level": "{{ .log_level }}",
+        "logToFile": {{ .log_to_file }},
+        "maxFiles": {{ .log_max_files }},
+        "filename": "/config/zwave",
         "forceConsole": true
     },
     "storage": {
-        "cacheDir": "/data/cache",
+        "cacheDir": "/config/cache",
         "throttle": "slow"
     },
     "securityKeys": {

zwave_js/translations/en.yaml

@@ -11,6 +11,17 @@ configuration:
   log_level:
     name: Log Level
     description: This option sets the log level of Z-Wave JS.
+  log_to_file:
+    name: Log to File?
+    description: >-
+      When this option is enabled, logs will be written to the
+      `/addon_configs/core_zwave_js` folder with the `.log` file extension.
+  log_max_files:
+    name: Max number of log files to keep
+    description: >-
+      When `log_to_file` is true, Z-Wave JS will create a log file for each
+      day. This option allows you to control the maximum number of files that
+      Z-Wave JS will keep.
   network_key:
     name: Network Key
     description: >-