fix: managed-mode install aborted with "Invalid download URL scheme: null"

bashio::config returns the literal string "null" for unset optional fields
(upstream bashio's ${2:-null} rewrites an empty default to "null"), so the
install script's [[ -z ... ]] check never fired and DOWNLOAD_URL stayed as
"null" when cgate_download_url was not overridden. The URL-scheme validator
then aborted, breaking managed-mode C-Gate installs. Same latent bug in the
SHA256 path.

URL and SHA256 resolution are extracted into helpers that treat both empty
and "null" as unset, with regression tests via a sourceable bashio stub.

Bumps add-on to 1.8.8.

Author: dougrathbone

homeassistant-addon/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to the C-Gate Web Bridge Home Assistant add-on will be docum
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.8] - 2026-05-07
+
+### Fixed
+- **Managed mode install failed with "Invalid download URL scheme: null"**: when running the add-on in managed mode without overriding `cgate_download_url`, the install script would log `Downloading C-Gate from: null` and abort. Root cause: `bashio::config 'cgate_download_url' ''` returns the literal string `"null"` for unset optional fields (upstream bashio's `${2:-null}` rewrites an empty default to `"null"`), so the script's `[[ -z … ]]` empty-check never fired and the hardcoded fallback URL was never applied. The install script now treats both empty and `"null"` as unset for `cgate_download_url` and `cgate_download_sha256`, and the URL/SHA resolution is extracted into helpers covered by unit tests.
+
 ## [1.8.7] - 2026-05-05
 
 ### Fixed

homeassistant-addon/config.yaml

@@ -1,5 +1,5 @@
 name: "C-Gate Web Bridge"
-version: "1.8.7"
+version: "1.8.8"
 slug: cgateweb
 description: "Bridge between Clipsal C-Bus systems and MQTT/Home Assistant"
 url: "https://github.com/dougrathbone/cgateweb"

homeassistant-addon/rootfs/etc/cont-init.d/cgate-install.sh

@@ -3,6 +3,35 @@
 # Install C-Gate if running in managed mode
 # ==============================================================================
 
+CGATEWEB_DEFAULT_DOWNLOAD_URL="https://download.se.com/files?p_Doc_Ref=C-Gate_3_Linux_Package_V3.3.2"
+
+# bashio::config returns the literal string "null" for unset optional fields,
+# even when an empty default is passed (upstream bashio's `${2:-null}` rewrites
+# an empty default to "null"). Treat both empty and "null" as unset.
+_cgateweb_resolve_download_url() {
+    local url
+    url=$(bashio::config 'cgate_download_url')
+    if [[ -z "${url}" || "${url}" == "null" ]]; then
+        url="${CGATEWEB_DEFAULT_DOWNLOAD_URL}"
+    fi
+    printf '%s' "${url}"
+}
+
+_cgateweb_resolve_download_sha256() {
+    local sha
+    sha=$(bashio::config 'cgate_download_sha256')
+    if [[ "${sha}" == "null" ]]; then
+        sha=""
+    fi
+    printf '%s' "${sha}"
+}
+
+# Allow tests to source this script for unit testing the helpers above without
+# running the install flow.
+if [[ "${CGATEWEB_INSTALL_SOURCE_ONLY:-0}" == "1" ]]; then
+    return 0 2>/dev/null || exit 0
+fi
+
 CGATE_MODE=$(bashio::config 'cgate_mode' 'remote')
 
 if [[ "${CGATE_MODE}" != "managed" ]]; then
@@ -13,7 +42,7 @@ fi
 CGATE_DIR="/data/cgate"
 CGATE_JAR="${CGATE_DIR}/cgate.jar"
 INSTALL_SOURCE=$(bashio::config 'cgate_install_source' 'download')
-DOWNLOAD_SHA256=$(bashio::config 'cgate_download_sha256' '')
+DOWNLOAD_SHA256=$(_cgateweb_resolve_download_sha256)
 WORK_DIR=$(mktemp -d /tmp/cgate-install.XXXXXX)
 
 cleanup() {
@@ -32,10 +61,7 @@ bashio::log.info "C-Gate not found, installing from source: ${INSTALL_SOURCE}"
 mkdir -p "${CGATE_DIR}"
 
 if [[ "${INSTALL_SOURCE}" == "download" ]]; then
-    DOWNLOAD_URL=$(bashio::config 'cgate_download_url' '')
-    if [[ -z "${DOWNLOAD_URL}" ]]; then
-        DOWNLOAD_URL="https://download.se.com/files?p_Doc_Ref=C-Gate_3_Linux_Package_V3.3.2"
-    fi
+    DOWNLOAD_URL=$(_cgateweb_resolve_download_url)
 
     bashio::log.info "Downloading C-Gate from: ${DOWNLOAD_URL}"
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cgateweb",
-  "version": "1.8.7",
+  "version": "1.8.8",
   "description": "Node.js bridge connecting Clipsal C-Bus automation systems to MQTT for Home Assistant integration",
   "keywords": [
     "cbus",

tests/cgateInstallScript.test.js

@@ -0,0 +1,84 @@
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const SCRIPT = path.join(
+    __dirname,
+    '..',
+    'homeassistant-addon',
+    'rootfs',
+    'etc',
+    'cont-init.d',
+    'cgate-install.sh'
+);
+
+const DEFAULT_DOWNLOAD_URL = 'https://download.se.com/files?p_Doc_Ref=C-Gate_3_Linux_Package_V3.3.2';
+
+// Real bashio's bashio::config returns the literal string "null" when a key
+// is unset, even when the caller passes an empty string as the default
+// (because upstream bashio uses `local default_value=${2:-null}`, which
+// substitutes "null" for both unset AND empty defaults).
+//
+// This stub mirrors that behavior. Test config is passed via env vars named
+// CGW_TEST_<key>; the stub returns the env value when set or the default
+// otherwise — matching real bashio's behavior including the "null" quirk.
+const BASHIO_STUB = `
+    bashio::log.info()    { :; }
+    bashio::log.warning() { :; }
+    bashio::log.error()   { :; }
+    bashio::log.trace()   { :; }
+    bashio::config() {
+        local key="$1"
+        local default_value="\${2:-null}"
+        local var_name="CGW_TEST_\${key}"
+        if declare -p "$var_name" &>/dev/null; then
+            printf '%s' "\${!var_name}"
+        else
+            printf '%s' "$default_value"
+        fi
+    }
+`;
+
+function callHelper(helperName, configObject) {
+    const env = { ...process.env, CGATEWEB_INSTALL_SOURCE_ONLY: '1' };
+    for (const [k, v] of Object.entries(configObject || {})) {
+        env[`CGW_TEST_${k}`] = v;
+    }
+    const script = `
+        set -u
+        ${BASHIO_STUB}
+        source "${SCRIPT}"
+        ${helperName}
+    `;
+    return execFileSync('bash', ['-c', script], { encoding: 'utf8', env });
+}
+
+describe('cgate-install.sh helpers', () => {
+    describe('_cgateweb_resolve_download_url', () => {
+        test('falls back to default URL when cgate_download_url is unset', () => {
+            const url = callHelper('_cgateweb_resolve_download_url', {});
+            expect(url).toBe(DEFAULT_DOWNLOAD_URL);
+        });
+
+        test('uses configured URL when cgate_download_url is set', () => {
+            const url = callHelper('_cgateweb_resolve_download_url', {
+                cgate_download_url: 'https://example.com/cgate.zip'
+            });
+            expect(url).toBe('https://example.com/cgate.zip');
+        });
+    });
+
+    describe('_cgateweb_resolve_download_sha256', () => {
+        test('returns empty string when cgate_download_sha256 is unset', () => {
+            const sha = callHelper('_cgateweb_resolve_download_sha256', {});
+            expect(sha).toBe('');
+        });
+
+        test('returns configured checksum when cgate_download_sha256 is set', () => {
+            const expected = 'a'.repeat(64);
+            const sha = callHelper('_cgateweb_resolve_download_sha256', {
+                cgate_download_sha256: expected
+            });
+            expect(sha).toBe(expected);
+        });
+    });
+});