homebridge-eosstb 2.4.0-beta.1 → 2.4.0-beta.3

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 See the [Readme file](https://github.com/jsiegenthaler/homebridge-eosstb/blob/master/README.md) for full plugin documentation.
 Please restart Homebridge after every plugin update.
 
+
+## 2.4.0-beta.3 (2026-05-10)
+
+This release focusses improved error handling and has extra debugging added to catch a refresh error
+
+- Improved handling of errors for web requests
+- Added extra debugging to assist in catching a refresh error in refreshChannelList 
+
+## 2.4.0-beta.2 (2026-05-09)
+
+This release focusses on ensuring mqtt long-term stability, and fixes an issue where the channel name was not shown on startup.
+
+- Rescheduled nightly channel list refresh to 0000-0400 instead of 0000-0600
+- Added an automatic daily mqtt reconnect at a random time between 0400-0600 to avoid long running mqtt sessions. Only restarts if settop box is turned off
+- Fixed issue where current channel was not displayed on plugin startup
+
+
 ## 2.4.0-beta.1 (2026-05-09)
 
 This release represents a major rewrite of the plugin, significantly improving robustness, HAP compliance, and code quality throughout, and making it work for Switzerland.
@@ -34,6 +51,20 @@ This release represents a major rewrite of the plugin, significantly improving r
 - Bumped dependency "tough-cookie": "^6.0.1",
 - Bumped dependency "ws": "^8.20.0"   
 
+## 2.3.9 (2026-05-09)
+- Fixed Error on Homebridge v2: Cannot read properties of undefined (reading 'STRING')
+- Adapted hidden channel name to reduce warning messages with Homebridge v2
+- Updated iOS and Homebridge version references in Readme
+- Bumped engine "^1.11.4||^2.0.0",
+- Bumped engine "node": "^24.15.0"
+- Bumped dependency "axios": "^1.16.0",
+- Bumped dependency "axios-cookiejar-support": "^7.0.0",
+- Bumped dependency "mqtt": "^5.15.1",
+- Bumped dependency "qs": "^6.15.1",
+- Bumped dependency "semver": "^7.8.0",
+- Bumped dependency "tough-cookie": "^6.0.1",
+- Bumped dependency "ws": "^8.20.0"   
+
 ## 2.3.8 (2026-02-27)
 
 This is a maintenance release to bring dependencies up to date.

package/README.md

@@ -20,7 +20,6 @@
 
 The logon method to the backend systems changed in January / February 2024. I managed to get CH working again from April 2026 for CH. NL was confirmed working OK in May 2026. BE was confirmed working OK in June 2024.
 
-If you know anything about session authentication and are able to help, please get in touch.
 </b><hr>
 
 [![npm](https://badgen.net/npm/dt/homebridge-eosstb)](https://www.npmjs.com/package/homebridge-eosstb)
@@ -110,7 +109,7 @@ This plugin is not provided by Telenet or Sunrise or Virgin Media or Ziggo or an
 ## Requirements
 
 - An Apple iPhone or iPad with iOS/iPadOS 14.0 (or later). Developed on iOS 14.1-26.4, earlier versions not tested.
-- [Homebridge](https://homebridge.io/) v1.1.116 (or later). Developed on Homebridge 1.1.116-2.0.1, earlier versions not tested.
+- [Homebridge](https://homebridge.io/) v1.1.116 (or later). Developed on Homebridge 1.1.116-2.0.2, earlier versions not tested.
 - A TV subscription from one of the supported countries and TV providers.
 - An online account for viewing TV in the web app (often part of your TV package), see the table above.
 - An ARRIS DCX960 or HUMAX EOS1008R / 2008C / VIP5002W set-top box, provided by your TV provider as part of your TV subscription, called by the system an "EOSSTB", "EOS2STB" or "APLSTB" and marketed under different names in different countries.

package/index.js

@@ -355,8 +355,10 @@ class StbPlatform {
     this.accessories = [];
     this.stbDevices = []; // store stbDevice in this.stbDevices
     this.masterChannelList = [];
-    this.masterChannelListExpiryDate = 0; // epoch = always expired on first run
+    this.masterChannelListRefreshedAt = null; // null = never fetched since startup
+    this.masterChannelListExpiryDate  = 0;    // epoch = always expired on first run, forces immediate fetch    
     this.checkChannelListTimeout = null; // nightly scheduler handler
+    this.mqttReconnecting = false; // nightly reconnect indicator
     this.isDev = config.devMode === true;
     this.debugLevel = this.config.debugLevel || 0; // debugLevel defaults to 0 (minimum)
 
@@ -822,7 +824,7 @@ class StbPlatform {
 
   /**
    * Schedule the next nightly master channel list refresh.
-   * Picks a random time between 00:00 and 06:00 the following day,
+   * Picks a random time between 00:00 and 04:00 the following day,
    * then reschedules itself so the pattern repeats indefinitely.
    *
    * Using setTimeout (not setInterval) means each day gets a fresh
@@ -834,9 +836,9 @@ class StbPlatform {
     tomorrow.setDate(tomorrow.getDate() + 1);
     tomorrow.setHours(0, 0, 0, 0);
 
-    // Add a random offset: anywhere from 0 ms up to (but not including) 6 hours
-    const SIX_HOURS_MS = 6 * 60 * 60 * 1000;
-    const randomOffsetMs = Math.floor(Math.random() * SIX_HOURS_MS);
+    // Add a random offset: anywhere from 0 ms up to (but not including) 4 hours
+    const FOUR_HOURS_MS = 4 * 60 * 60 * 1000;
+    const randomOffsetMs = Math.floor(Math.random() * FOUR_HOURS_MS);
 
     const nextRefreshAt = new Date(tomorrow.getTime() + randomOffsetMs);
     const msUntilRefresh = nextRefreshAt.getTime() - Date.now();
@@ -850,11 +852,125 @@ class StbPlatform {
     // Store the timer handle so shutdown can cancel it
     this.checkChannelListTimeout = setTimeout(async () => {
       if (this.isShuttingDown) return; // bail out if we're going down
+
+      // if an MQTT reconnect is in progress, wait a few minutes before
+      // refreshing to avoid a race condition during session startup
+      if (this.mqttReconnecting) {
+        const THREE_MIN_MS = 3 * 60 * 1000;
+        const retryDelayMs =
+          THREE_MIN_MS + Math.floor(Math.random() * THREE_MIN_MS);
+        this.log.info(
+          "StbPlatform: channel list refresh deferred - MQTT reconnect in progress, retrying in a few minutes",
+        );
+        this.checkChannelListTimeout = setTimeout(async () => {
+          if (this.isShuttingDown) return;
+          await this._refreshChannelList();
+          this._scheduleNightlyChannelListRefresh();
+        }, retryDelayMs);
+        return;
+      }
+
       await this._refreshChannelList();
       this._scheduleNightlyChannelListRefresh(); // reschedule for the next day
     }, msUntilRefresh);
   } // end of _scheduleNightlyChannelListRefresh
 
+  /**
+   * Schedule the next nightly MQTT reconnect.
+   * Picks a random time between 04:00 and 06:00 the following day
+   * to avoid overlapping with the channel list refresh (00:00–04:00).
+   * Reschedules itself so the pattern repeats indefinitely.
+   */
+  _scheduleNightlyMqttReconnect() {
+    const tomorrow = new Date();
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    tomorrow.setHours(4, 0, 0, 0);
+
+    const TWO_HOURS_MS = 2 * 60 * 60 * 1000;
+    const randomOffsetMs = Math.floor(Math.random() * TWO_HOURS_MS);
+
+    const nextReconnectAt = new Date(tomorrow.getTime() + randomOffsetMs);
+    const msUntilReconnect = nextReconnectAt.getTime() - Date.now();
+
+    if (this.debugLevel > 0) {
+      this.log.warn(
+        `StbPlatform: next nightly MQTT reconnect scheduled for ${nextReconnectAt.toLocaleString()}`,
+      );
+    }
+
+    this.mqttReconnectTimeout = setTimeout(async () => {
+      if (this.isShuttingDown) return;
+      await this._attemptNightlyMqttReconnect();
+      // _attemptNightlyMqttReconnect reschedules for the next night once done
+    }, msUntilReconnect);
+  } // end of _scheduleNightlyMqttReconnect
+
+  /**
+   * Attempt the nightly MQTT reconnect.
+   * If any STB is currently online (user may be watching), defers by 1 hour
+   * plus a random offset and tries again, rather than interrupting the session.
+   * Once the reconnect completes (or fails), reschedules for the next night.
+   * Retries 3 times then gives up, and the next reconnect will be the next day.
+   */
+  async _attemptNightlyMqttReconnect(retryCount = 0) {
+    if (this.isShuttingDown) return;
+
+    const MAX_RETRIES = 3; // give up after 3 deferrals (~3-4.5 hours past 04:00)
+
+    // check if any STB is currently active - if so, defer to avoid
+    // interrupting a user who may be watching TV and using the remote
+    const anyStbOnline = this.devices.some(
+      (device) => device.currentPowerState === Characteristic.Active.ACTIVE,
+    );
+
+    if (anyStbOnline) {
+      // give up if max retries reached
+      if (retryCount >= MAX_RETRIES) {
+        this.log.info(
+          "StbPlatform: nightly MQTT reconnect skipped - STB still active after max retries, rescheduling for next night",
+        );
+        this._scheduleNightlyMqttReconnect();
+        return;
+      }
+
+      // retry in 1 hour plus a random 0–30 min buffer
+      const ONE_HOUR_MS = 60 * 60 * 1000;
+      const THIRTY_MIN_MS = 30 * 60 * 1000;
+      const retryDelayMs =
+        ONE_HOUR_MS + Math.floor(Math.random() * THIRTY_MIN_MS);
+      const retryAt = new Date(Date.now() + retryDelayMs);
+
+      this.log.info(
+        `StbPlatform: nightly MQTT reconnect deferred - STB is active (attempt ${retryCount + 1}/${MAX_RETRIES}). Retrying at ${retryAt.toLocaleString()}`,
+      );
+
+      // store handle so shutdown can cancel the deferred retry too
+      this.mqttReconnectTimeout = setTimeout(async () => {
+        if (this.isShuttingDown) return;
+        await this._attemptNightlyMqttReconnect(retryCount + 1);
+      }, retryDelayMs);
+      return; // don't reschedule for next night yet - that happens after a successful reconnect
+    }
+
+    // no STB is active - safe to reconnect
+    try {
+      this.mqttReconnecting = true; // signal to channel list refresh to pause
+      this.log.info("StbPlatform: nightly MQTT reconnect starting...");
+      await this.endMqttSession();
+      await this.startMqttClient();
+      this.log.info("StbPlatform: nightly MQTT reconnect completed");
+    } catch (err) {
+      this.log.error(
+        "StbPlatform: nightly MQTT reconnect failed:",
+        err.message,
+      );
+    } finally {
+      this.mqttReconnecting = false; // always clear the flag, even on failure
+    }
+
+    this._scheduleNightlyMqttReconnect(); // reschedule for next night
+  } // end of _attemptNightlyMqttReconnect
+
   /**
    * _runFullStartupSequence
    *
@@ -872,7 +988,7 @@ class StbPlatform {
    *  10.  startMqttClient      — connect to the mqtt broker
    *
    * Each step is individually awaited, so failures are caught at the right
-   * step and errorTitle is accurate when logged.
+   * step and stepName is accurate when logged.
    *
    * @param {string} watchdogInstance - log prefix for this watchdog invocation
    * @param {string} debugPrefix      - debug() colour prefix
@@ -883,12 +999,13 @@ class StbPlatform {
       Object.keys(sessionState)[this.currentSessionState],
     );
 
-    // errorTitle tracks which step we're on so the catch block can log a
+    // stepName tracks which step we're on so the catch block can log a
     // meaningful message rather than a generic "something failed".
-    let errorTitle = "Failed to get config";
+    let stepName = "";
 
     try {
       // ── Step 1: Get backend config (endpoint URLs) for the country ──────────
+      stepName = "get config";
       this.log.debug("%s: ++++ step 1: calling getConfig", watchdogInstance);
       debug(debugPrefix + "calling getConfig");
 
@@ -902,7 +1019,7 @@ class StbPlatform {
       );
 
       // ── Step 2: Authenticate and create a session ──────────────────────────
-      errorTitle = "Failed to create session";
+      stepName = "create session";
       this.log.debug(
         "%s: ++++ step 2: calling createSession for country %s",
         watchdogInstance,
@@ -913,6 +1030,12 @@ class StbPlatform {
 
       const sessionHouseholdId = await this.createSession();
       // Result stored in this.session by createSession()
+      // debugging help to get session keys
+      // session object keys: ["accessToken","householdId","refreshToken","refreshTokenExpiry","username","issuedAt"]
+      this.log.debug(
+        "session object keys: %s",
+        JSON.stringify(Object.keys(this.session ?? {})),
+      );
 
       this.log.debug(
         "%s: ++++++ step 2 done: session created, householdId %s",
@@ -921,7 +1044,7 @@ class StbPlatform {
       );
 
       // ── Step 3: Fetch customer profile and assigned devices ────────────────
-      errorTitle = "Failed to discover platform";
+      stepName = "discover platform";
       this.log.debug(
         "%s: ++++ step 3: calling getPersonalizationData for householdId %s",
         watchdogInstance,
@@ -1017,7 +1140,7 @@ class StbPlatform {
       }
 
       // ── Step 8: Discover and configure HomeKit accessories ─────────────────
-      errorTitle = "Failed to discover devices";
+      stepName = "discover devices";
       this.log.debug(
         "%s: ++++ step 8: calling discoverDevices",
         watchdogInstance,
@@ -1035,7 +1158,7 @@ class StbPlatform {
       );
 
       // ── Step 9: Get the mqtt broker token ─────────────────────────────────
-      errorTitle = "Failed to start mqtt session";
+      stepName = "start mqtt session";
       this.log.debug("%s: ++++ step 9: calling getMqttToken", watchdogInstance);
       debug(debugPrefix + "calling getMqttToken");
 
@@ -1072,15 +1195,66 @@ class StbPlatform {
         watchdogInstance,
       );
     } catch (errorReason) {
-      // One of the steps above threw or rejected. Log the failed step name
-      // (errorTitle) alongside the reason for easy diagnosis.
-      this.log.warn("%s: %s — %s", watchdogInstance, errorTitle, errorReason);
+      // One of the steps above threw or rejected. Log the failed stepName
+      // alongside the error message for easy diagnosis.
+      const errMsg =
+        errorReason instanceof Error
+          ? errorReason.message
+          : String(errorReason);
+      this.log.warn("%s: Failed to %s: %s", watchdogInstance, stepName, errMsg);
       this.currentSessionState = sessionState.DISCONNECTED;
       this.currentStatusFault = Characteristic.StatusFault.GENERAL_FAULT;
       // sessionWatchdogRunning is reset in the finally block of the caller.
     }
   } // end of _runFullStartupSequence
 
+  /**
+   * _handleWebError
+   *
+   * Standardised catch-block handler for all outbound HTTP/Axios calls.
+   * Builds a consistent human-readable error message, sets session state
+   * to DISCONNECTED on ENOTFOUND, logs at debug level, then re-throws.
+   *
+   * @param {Error}  error   - the caught error
+   * @param {string} action  - what the caller was trying to do, e.g.
+   *                           "get config data for countryCode ch"
+   * @param {string|URL} url - the URL that was called (for debug context)
+   */
+  _handleWebError(error, action, url) {
+    const urlStr = String(url ?? error.config?.url ?? "");
+    let errReason = `Could not ${action}:`;
+
+    if (error.isAxiosError) {
+      errReason += ` ${error.code}`;
+
+      if (error.response) {
+        errReason += ` (HTTP ${error.response.status})`;
+      }
+
+      if (error.code === "ENOTFOUND") {
+        errReason += " - no internet connection";
+        this.currentSessionState = sessionState.DISCONNECTED;
+      }
+    } else {
+      errReason += ` — ${error.message ?? String(error)}`;
+    }
+
+    if (urlStr) errReason += ` — ${urlStr}`;
+
+    // Summary always visible:
+    this.log.error("_handleWebError: %s", errReason);
+
+    this.log.debug("_handleWebError: %s — full error:", errReason, error);
+    if (error.response?.data) {
+      this.log.debug(
+        "_handleWebError: response body: %s",
+        JSON.stringify(error.response.data).substring(0, 400),
+      );
+    }
+
+    throw new Error(errReason, { cause: error });
+  }
+
   /**
    * Discovers all physical devices from the backend and maps them to HomeKit accessories.
    * Creates new accessories for uncached devices, and restores existing ones from cache.
@@ -2609,8 +2783,8 @@ class StbPlatform {
           );
         }
         throw new Error(
-          `Step 4 of 5: login did not redirect to login_success.html — ` +
-            `check your username and password. Final URL: ${finalUrl}`,
+          // use a simple clean message to tell the user his credentials are likely wrong
+          `Step 4 of 5: login failed — check your username and password`,
         );
       }
 
@@ -3136,6 +3310,18 @@ class StbPlatform {
       return;
     }
 
+    // Log session state before the request - DIAGNOSES DEBUG ONLY
+    const tokenAge = this.session?.issuedAt
+      ? Math.round((Date.now() - this.session.issuedAt) / 1000 / 60)
+      : null;
+    const sessionId = this.session?.householdId ?? "(none)";
+
+    this.log.debug(
+      "refreshMasterChannelList: starting | householdId=%s | tokenAgeMinutes=%s",
+      sessionId,
+      tokenAge ?? "unknown",
+    );
+
     // exit immediately if channel list has not expired
     if (Date.now() < this.masterChannelListExpiryDate) {
       if (this.debugLevel > 1) {
@@ -3154,16 +3340,6 @@ class StbPlatform {
     // syntax:
     // https://prod.oesp.virginmedia.com/oesp/v4/GB/eng/web/channels?byLocationId=41043&includeInvisible=true&includeNotEntitled=true&personalised=true&sort=channelNumber
     // https://prod.spark.sunrisetv.ch/eng/web/linear-service/v2/channels?cityId=401&language=en&productClass=Orion-DASH
-    /*
-			let url = COUNTRY_BASE_URLS[this.config.country.toLowerCase()] + '/channels';
-			url = url + '?byLocationId=' + this.session.locationId // locationId needed to get user-specific list
-			url = url + '&includeInvisible=true' // includeInvisible
-			url = url + '&includeNotEntitled=true' // includeNotEntitled
-			url = url + '&personalised=true' // personalised
-			url = url + '&sort=channelNumber' // sort
-			*/
-    //url = 'https://prod.spark.sunrisetv.ch/eng/web/linear-service/v2/channels?cityId=401&language=en&productClass=Orion-DASH'
-    //let url = COUNTRY_BASE_URLS[this.config.country.toLowerCase()] + '/eng/web/linear-service/v2/channels';
     const url = new URL(`${this.configsvc.linearService.URL}/v2/channels`);
     url.searchParams.set("cityId", this.customer.cityId);
     url.searchParams.set("language", "en");
@@ -3172,6 +3348,7 @@ class StbPlatform {
     if (this.debugLevel > 1) {
       this.log.warn("refreshMasterChannelList: GET %s", url);
     }
+
     try {
       // call the webservice to get all available channels
       const config = {
@@ -3186,6 +3363,29 @@ class StbPlatform {
             "https://www.horizon.tv/",
         },
       };
+      // extra debugging to help catch refresh issues
+      this.log.debug(
+        "refreshMasterChannelList: request headers | x-oesp-token=%s...%s | x-oesp-username=%s | Referer=%s",
+        this.session.accessToken?.substring(0, 8) ?? "(null)", // first 8 chars only — don't log the full token
+        this.session.accessToken?.slice(-4) ?? "", // last 4 chars
+        this.session.username ?? "(null)",
+        config.headers.Referer,
+      );
+      // extra debugging to help catch refresh issues
+      this.log.debug(
+        "refreshMasterChannelList: preflight | cityId=%s | tokenPresent=%s | tokenLength=%s | username=%s | prevExpiryWas=%s | lastRefreshedAt=%s",
+        this.customer.cityId,
+        !!this.session?.accessToken,
+        this.session?.accessToken?.length ?? 0,
+        this.session?.username ?? "(none)",
+        this.masterChannelListExpiryDate
+          ? new Date(this.masterChannelListExpiryDate).toLocaleString()
+          : "(never set)",
+        this.masterChannelListRefreshedAt
+          ? new Date(this.masterChannelListRefreshedAt).toLocaleString()
+          : "(never)",
+      );
+
       const response = await axiosWS(config);
       if (this.debugLevel > 1) {
         this.log.warn(
@@ -3198,7 +3398,6 @@ class StbPlatform {
           response.data.length,
         );
       }
-      //this.log(response.data);
 
       // the header contains the following:
       // Cache-Control: max-age=600, public, stale-if-error=43200
@@ -3239,6 +3438,9 @@ class StbPlatform {
         this.masterChannelList.map((ch) => [ch.id, ch]),
       );
 
+      // record when we refreshed it
+      this.masterChannelListRefreshedAt = Date.now()
+
       this.log(
         "MasterChannelList contains %s channels, valid until %s",
         this.masterChannelList.length,
@@ -3254,15 +3456,11 @@ class StbPlatform {
       }
       return this.masterChannelList;
     } catch (error) {
-      const errReason = error.isAxiosError
-        ? `${error.code}: ${error.hostname ?? error.config?.url ?? ""}`
-        : (error.message ?? String(error));
-
-      if (error.isAxiosError && error.code === "ENOTFOUND") {
-        this.currentSessionState = sessionState.DISCONNECTED;
-      }
-      this.log.warn("refreshMasterChannelList error:", errReason);
-      throw new Error(errReason, { cause: error }); // { cause } preserves the original for debugging
+      this._handleWebError(
+        error,
+        `refresh master channel list`,
+        url,
+      );
     }
   } // end of refreshMasterChannelList
 
@@ -3327,16 +3525,11 @@ class StbPlatform {
       this.configsvc = response.data; // store the entire config data for future use in this.configsvc
       return this.configsvc;
     } catch (error) {
-      let errReason = `Could not get config data for ${countryCode} - check your internet connection`;
-      if (error.isAxiosError) {
-        errReason = error.code + ": " + (error.hostname || "");
-        // if no connection then set session to disconnected to force a session reconnect
-        if (error.code === "ENOTFOUND") {
-          this.currentSessionState = sessionState.DISCONNECTED;
-        }
-      }
-      this.log.debug(`getConfig error:`, error);
-      throw new Error(errReason);
+      this._handleWebError(
+        error,
+        `get config data for countryCode ${countryCode}`,
+        url,
+      );
     }
   } // end of getConfig
 
@@ -3487,20 +3680,11 @@ class StbPlatform {
       //this.log.warn('getPersonalizationData: all done, returnng customerStatus: %s', this.customer.customerStatus);
       return this.customer;
     } catch (error) {
-      let errReason =
-        "Could not refresh personalization data for " +
-        householdId +
-        " - check your internet connection";
-      if (error.isAxiosError) {
-        errReason = error.code + ": " + (error.hostname || "");
-        // if no connection then set session to disconnected to force a session reconnect
-        if (error.code === "ENOTFOUND") {
-          this.currentSessionState = sessionState.DISCONNECTED;
-        }
-      }
-      //this.log('%s %s', errText, (errReason || ''));
-      this.log.debug(`getPersonalizationData error:`, error);
-      throw error;
+      this._handleWebError(
+        error,
+        `get personalization data for household ${householdId}`,
+        url,
+      );
     }
   } // end of getPersonalizationData
 
@@ -3550,12 +3734,11 @@ class StbPlatform {
         );
       }
     } catch (error) {
-      this.log.warn(
-        "setPersonalizationDataForDevice failed: %s %s",
-        error.response?.status,
-        error.response?.statusText,
+      this._handleWebError(
+        error,
+        `set personalization data for device ${deviceId}`,
+        url,
       );
-      this.log.debug("setPersonalizationDataForDevice: error:", error);
     }
   } // end of setPersonalizationDataForDevice
 
@@ -3614,15 +3797,11 @@ class StbPlatform {
       }
       return this.entitlements;
     } catch (error) {
-      let errReason = `Could not refresh entitlements data for ${householdId} - check your internet connection`;
-      if (error.isAxiosError) {
-        errReason = `${error.code}: ${error.hostname || ""}`;
-      }
-      if (error.code === "ENOTFOUND") {
-        this.currentSessionState = sessionState.DISCONNECTED;
-      }
-      this.log.debug(`getEntitlements error:`, error);
-      throw new Error(errReason);
+      this._handleWebError(
+        error,
+        `get entitlements data for household ${householdId}`,
+        url,
+      );
     }
   } // end of getEntitlements
 
@@ -3799,29 +3978,11 @@ class StbPlatform {
 
       return this.currentRecordingState;
     } catch (error) {
-      if (error.isAxiosError) {
-        const errReason =
-          "getRecordingState" +
-          ": " +
-          error.code +
-          " " +
-          (error.hostname || "") +
-          ": " +
-          (error.response?.status ?? "") +
-          " " +
-          (error.response?.statusText ?? "") +
-          ": " +
-          (error.config?.url ?? "");
-        if (error.code === "ENOTFOUND") {
-          this.currentSessionState = sessionState.DISCONNECTED;
-        }
-        this.log.debug("getRecordingState error:", error);
-        throw new Error(errReason);
-      } else {
-        this.log.warn("getRecordingState error:");
-        this.log.warn(error);
-        throw error;
-      }
+      this._handleWebError(
+        error,
+        `get recording status for household ${householdId}`,
+        url,
+      );
     }
   } // end of getRecordingState
 
@@ -4011,29 +4172,11 @@ class StbPlatform {
 
       return this.currentRecordingState;
     } catch (error) {
-      if (error.isAxiosError) {
-        const errReason =
-          "getRecordingBookings" +
-          ": " +
-          error.code +
-          " " +
-          (error.hostname || "") +
-          ": " +
-          (error.response?.status ?? "") +
-          " " +
-          (error.response?.statusText ?? "") +
-          ": " +
-          (error.config?.url ?? "");
-        if (error.code === "ENOTFOUND") {
-          this.currentSessionState = sessionState.DISCONNECTED;
-        }
-        this.log.debug("getRecordingBookings error:", error);
-        throw new Error(errReason);
-      } else {
-        this.log.warn("getRecordingBookings error:");
-        this.log.warn(error);
-        throw error;
-      }
+      this._handleWebError(
+        error,
+        `get recording bookings for household ${householdId}`,
+        url,
+      );
     }
   } // end of getRecordingBookings
 
@@ -4070,14 +4213,11 @@ class StbPlatform {
       this.log.warn(response.data);
       return true;
     } catch (error) {
-      let errReason = `Could not get experimental data for ${householdId} - check your internet connection`;
-      if (error.isAxiosError) {
-        errReason = `${error.code}: ${error.hostname || ""}`;
-        if (error.code === "ENOTFOUND") {
-          this.currentSessionState = sessionState.DISCONNECTED;
-        }
-      }
-      this.log.warn(`getExperimentalEndpoint error:`, error);
+      this._handleWebError(
+        error,
+        `get experimental endpoint for household ${householdId}`,
+        url,
+      );
     }
   } // end of getExperimentalEndpoint
 
@@ -4278,12 +4418,8 @@ class StbPlatform {
           // ------ device subscriptions ------
           // subscribe only to what we need
 
-          // turn on our clientId. This is similar to turning on a box, it tells the server we are online
-          // our clientId must be up and running to send commands (power, channel, etc) to the physical device
-          // this.setHgoOnlineRunning(householdId, mqttClientId);
-
           // householdId/mqttClientId: subscribe to own clientId to get data for ourselves
-          // subscribe to all devices after the setHgoOnlineRunning is sent
+          // subscribe to all devices before the setHgoState is sent
           this.mqttSubscribeToTopic(
             householdId + "/" + this.mqttClient.options.clientId,
           ); // subscribe to our own mqttClientId to get all data
@@ -4320,32 +4456,46 @@ class StbPlatform {
           // reset so the 10-second retry fires correctly if the box doesn't respond
           this.lastMqttUiStatusMessageReceived = null;
 
+          // announce ourselves as an active HGO client before requesting UI status
+          // the STB uses this retained presence message to decide which clients to respond to
+          this.setHgoState(
+            householdId,
+            this.mqttClient.options.clientId,
+            "ONLINE_RUNNING",
+          );
+
+          // request initial UI status for each device, with a short delay to allow
+          // the STB to process the HGO presence announcement first
           // CPE.uiStatus messages are received via the householdId and mqttClientId
           // topics which are already subscribed above.
           // getUiStatus is called here to request the initial UI state from each device.
           // retain: false is used (see getUiStatus) so a retry is scheduled in case the box
           // is temporarily unreachable when the initial request is sent.
-          this.devices.forEach((device) => {
-            // request the initial UI status for each device
-            this.getUiStatus(device.deviceId, this.mqttClient.options.clientId);
-
-            // retry getUiStatus after 10 seconds if no CPE.uiStatus response has arrived yet
-            // (handles case where box is briefly offline when the initial request is sent)
-            setTimeout(() => {
-              if (!this.lastMqttUiStatusMessageReceived) {
-                if (this.debugLevel > 0) {
-                  this.log.warn(
-                    "getUiStatus: no CPE.uiStatus received yet for %s, retrying",
+          setTimeout(() => {
+            this.devices.forEach((device) => {
+              // request the initial UI status for each device
+              this.getUiStatus(
+                device.deviceId,
+                this.mqttClient.options.clientId,
+              );
+
+              // retry after 10 seconds if no CPE.uiStatus response has arrived yet
+              setTimeout(() => {
+                if (!this.lastMqttUiStatusMessageReceived) {
+                  if (this.debugLevel > 0) {
+                    this.log.warn(
+                      "getUiStatus: no CPE.uiStatus received yet for %s, retrying",
+                      device.deviceId,
+                    );
+                  }
+                  this.getUiStatus(
                     device.deviceId,
+                    this.mqttClient.options.clientId,
                   );
                 }
-                this.getUiStatus(
-                  device.deviceId,
-                  this.mqttClient.options.clientId,
-                );
-              }
-            }, 10 * 1000); // 10 second retry delay
-          });
+              }, 10 * 1000); // 10 second retry delay
+            });
+          }, 500); // 500ms for STB to register our HGO presence before we request status
 
           resolve(true); // all subscriptions registered — session is ready
         } catch (err) {
@@ -4445,7 +4595,8 @@ class StbPlatform {
               const deviceIndex = this.devices.findIndex(
                 (device) => device.deviceId === deviceId,
               );
-              const stbDevice = deviceIndex > -1 ? this.stbDevices[deviceIndex] : null;
+              const stbDevice =
+                deviceIndex > -1 ? this.stbDevices[deviceIndex] : null;
 
               // Box setting: StandbyPowerConsumption = FastStart / ActiveStart / EcoSlowstart
               // "Fast start":  when turned off, goes to ONLINE_STANDBY and stays there. Box can be turned on via mqtt
@@ -4458,15 +4609,18 @@ class StbPlatform {
                   // Detect power-off → power-on transition per device.
                   // Set PLAY immediately; CPE.uiStatus will overwrite with the
                   // accurate speed-derived state shortly after.
-                  if (stbDevice?.previousPowerState === Characteristic.Active.INACTIVE) {
+                  if (
+                    stbDevice?.previousPowerState ===
+                    Characteristic.Active.INACTIVE
+                  ) {
                     currMediaState = Characteristic.CurrentMediaState.PLAY;
                     if (this.debugLevel > 0) {
                       this.log.warn(
-                        "mqttClient: STB status: power-on transition for %s, setting mediaState to PLAY",
+                        "mqttClient: STB status: Power-on transition detected for %s, setting mediaState to PLAY",
                         deviceId,
                       );
                     }
-                  }                 
+                  }
                   break;
                 case "ONLINE_STANDBY": // ONLINE_STANDBY: power is off, device is on standby, still reachable over the network, can be turned on via mqtt.
                   currStatusActive = Characteristic.Active.ACTIVE; // bool, 0 = not active, 1 = active
@@ -4496,6 +4650,12 @@ class StbPlatform {
                 this.log.warn("mqttClient: %s %s", deviceId, stbState);
               }
             }
+
+            // After the switch, if box is running, request current UI state
+            //if (stbState === 'ONLINE_RUNNING') {
+            // Small delay gives the STB a moment to settle before responding
+            //setTimeout(() => this.mqttRequestUiStatus(deviceId), 500);
+            //}
           }
 
           // handle CPE UI status messages for the STB
@@ -4878,16 +5038,26 @@ class StbPlatform {
         return resolve(true);
       }
 
-      // unsubscribe from all subscribedTopics before tearing down the session
+      // get all subscribed topics
       const topics = this.subscribedTopics ?? [];
+
+      // announce HGO offline while the connection is still live, before any teardown
+      this.setHgoState(
+        this.session.householdId,
+        this.mqttClient.options.clientId,
+        "OFFLINE",
+      );
+
+      // unsubscribe from all subscribedTopics before tearing down the session
       if (topics.length === 0) {
         this.log.info(
           "mqttClient: No topics to unsubscribe from, skipping unsubscribe.",
         );
-        this.mqttClient.end(false, {}, (err) => {
-          if (err) {
-            this.log.error("MQTT end error:", err);
-            return reject(err);
+
+        this.mqttClient.end(false, {}, (endErr) => {
+          if (endErr) {
+            this.log.error("MQTT end error:", endErr);
+            return reject(endErr);
           }
           this.log.info(
             "mqttClient: Disconnected cleanly. No topics found to unsubscribe from.",
@@ -4897,15 +5067,15 @@ class StbPlatform {
         return;
       }
 
-      this.mqttClient.unsubscribe(topics, (err) => {
-        if (err) {
-          this.log.error("MQTT unsubscribe error:", err);
+      this.mqttClient.unsubscribe(topics, (unsubErr) => {
+        if (unsubErr) {
+          this.log.error("MQTT unsubscribe error:", unsubErr);
           // still attempt to end even if unsubscribe failed
         }
-        this.mqttClient.end(false, {}, (err) => {
-          if (err) {
-            this.log.error("MQTT end error:", err);
-            return reject(err);
+        this.mqttClient.end(false, {}, (endErr) => {
+          if (endErr) {
+            this.log.error("MQTT end error:", endErr);
+            return reject(endErr);
           }
           this.log.info(
             "mqttClient: Disconnected cleanly. All topics unsubscribed.",
@@ -4990,7 +5160,7 @@ class StbPlatform {
           "mqttPublishMessage: Publish Message:\r\nTopic: %s\r\nMessage: %s\r\nOptions: %s",
           Topic,
           Message,
-          Options,
+          JSON.stringify(Options),
         );
       }
       this.mqttClient.publish(Topic, Message, Options, (err) => {
@@ -5081,19 +5251,20 @@ class StbPlatform {
     });
   }
 
-  // start the HGO session (switch on)
-  setHgoOnlineRunning(householdId, mqttClientId) {
-    // {"source":"fd29b575-5f2b-49a0-8efe-62a844ac2b40","state":"ONLINE_RUNNING","deviceType":"HGO","mac":"","ipAddress":""}
+  // set the HGO session state (online or offline)
+  // called on mqtt connect (ONLINE_RUNNING) and on mqtt disconnect (OFFLINE)
+  // retain: true ensures the broker overwrites any previous retained state
+  setHgoState(householdId, mqttClientId, state) {
     const topic = `${householdId}/${mqttClientId}/status`;
     const message = JSON.stringify({
       source: mqttClientId,
-      state: "ONLINE_RUNNING",
+      state: state,
       deviceType: "HGO",
       mac: "",
       ipAddress: "",
     });
     if (this.debugLevel > 0) {
-      this.log.warn("setHgoOnlineRunning: publishing to topic:", topic);
+      this.log.warn("setHgoState: publishing %s to topic: %s", state, topic);
     }
     this.mqttPublishMessage(topic, message, { qos: 2, retain: true });
   }
@@ -5151,6 +5322,39 @@ class StbPlatform {
     }
   }
 
+  // Request the current UI status from the STB.
+  // The STB responds with a CPE.uiStatus message on the household channel.
+  // @param {string} deviceId - The STB device ID (e.g. "000378-EOS2STB-00852052xxxx")
+  mqttRequestUiStatus(deviceId) {
+    if (!this.mqttClient?.connected) {
+      this.log.warn(
+        "%s: mqttRequestUiStatus: MQTT not connected, skipping",
+        deviceId,
+      );
+      return;
+    }
+    if (this.debugLevel > 0) {
+      this.log.warn(
+        "mqttRequestUiStatus: Requesting UI status for %s",
+        deviceId,
+      );
+    }
+
+    const payload = JSON.stringify({
+      version: "1.3.18",
+      type: "CPE.pullFromTV",
+      source: this.mqttClient.options.clientId, // your mqttClientId
+      messageTimeStamp: Date.now(),
+    });
+
+    const topic = `${this.session.householdId}/${deviceId}`;
+
+    this.mqttPublishMessage(topic, payload, {
+      qos: 1,
+      retain: false,
+    });
+  }
+
   // set the media state of the settopbox via mqtt
   // media state is controlled by speedRate
   // speedRate can be one of: -64 -30 -6 -2 0 2 6 30 64. 0=Paused, 1=Play, >1=FastForward, <0=Rewind
@@ -6406,10 +6610,7 @@ class StbDevice {
       inputSourceService
         .getCharacteristic(Characteristic.ConfiguredName)
         .setProps({
-          perms: [
-            this.api.hap.Perms.PAIRED_READ,
-            this.api.hap.Perms.NOTIFY,
-          ],
+          perms: [this.api.hap.Perms.PAIRED_READ, this.api.hap.Perms.NOTIFY],
         })
         .onGet(() => this.getInputName(i));
       //.onSet((value) => this.setInputName(i, value));
@@ -7800,7 +8001,10 @@ class StbDevice {
     // triple rapid VolDown presses triggers setMute
     if (volumeSelectorValue === Characteristic.VolumeSelector.DECREMENT) {
       // Guard: ensure array is properly initialised
-      if (!Array.isArray(this.lastVolDownKeyPress) || this.lastVolDownKeyPress.length < 3) {
+      if (
+        !Array.isArray(this.lastVolDownKeyPress) ||
+        this.lastVolDownKeyPress.length < 3
+      ) {
         this.lastVolDownKeyPress = [0, 0, 0];
       }
 
@@ -7809,14 +8013,14 @@ class StbDevice {
       this.lastVolDownKeyPress = this.lastVolDownKeyPress.slice(0, 3); // keep only last 3
 
       // Now assign the calculated value to the outer variable
-      tripleVolDownPress = this.lastVolDownKeyPress[0] - this.lastVolDownKeyPress[2];
+      tripleVolDownPress =
+        this.lastVolDownKeyPress[0] - this.lastVolDownKeyPress[2];
 
       this.log.debug(
         "%s: setVolume: Timediff between volDownKeyPress[0] and volDownKeyPress[2]: %s ms",
         this.name,
         tripleVolDownPress,
-      );      
-      
+      );
     }
 
     // check for triple press of volDown, send setMute if tripleVolDownPress less than triplePressTime of 800ms
@@ -7854,7 +8058,11 @@ class StbDevice {
 
       try {
         if (this.debugLevel > 0) {
-          this.log.warn("%s: setVolume: Sending command %s", this.name, command);
+          this.log.warn(
+            "%s: setVolume: Sending command %s",
+            this.name,
+            command,
+          );
         }
         await new Promise((resolve, reject) => {
           exec(command, (error, _stdout, stderr) => {
@@ -8220,13 +8428,13 @@ class StbDevice {
     // logChangeOnly = TRUE: only the changes are logged, no media state change occurs. Needed when sending remote keypresses to prevent double commands
     // CHAR_NAMES: TargetMediaState: [ 'UUID', 'PLAY', 'PAUSE', 'STOP' ]
     //if (this.debugLevel > 1) {
-      this.log.info(
-        "%s: setTargetMediaState to %s [%s]",
-        this.name,
-        targetMediaState,
-        CHAR_NAMES.TargetMediaState[targetMediaState + 1],
-      );
-   // }
+    this.log.info(
+      "%s: setTargetMediaState to %s [%s]",
+      this.name,
+      targetMediaState,
+      CHAR_NAMES.TargetMediaState[targetMediaState + 1],
+    );
+    // }
 
     if (!logChangeOnly) {
       // send the setMediaState command if we are not just logging the change
@@ -8239,16 +8447,17 @@ class StbDevice {
       //  PLAY  0  -  1 Play
       //  PAUSE 1  -  0 Paused
       //  STOP  2  -  0 Paused
-      const newBoxMediaState = targetMediaState === Characteristic.TargetMediaState.PLAY ? 1 : 0;
+      const newBoxMediaState =
+        targetMediaState === Characteristic.TargetMediaState.PLAY ? 1 : 0;
       const newBoxMediaStateName = newBoxMediaState === 1 ? "Play" : "Paused";
 
       //if (this.debugLevel >= 0) {
-        this.log(
-          "%s: setTargetMediaState: Calling setMediaState with newBoxMediaState %s [%s]",
-          this.name,
-          newBoxMediaState,
-          newBoxMediaStateName,
-        );
+      this.log(
+        "%s: setTargetMediaState: Calling setMediaState with newBoxMediaState %s [%s]",
+        this.name,
+        newBoxMediaState,
+        newBoxMediaStateName,
+      );
       //}
       /*
       switch (targetMediaState) {

package/package.json

@@ -3,7 +3,7 @@
   "displayName": "Homebridge EOSSTB",
   "description": "Add your set-top box to Homekit (for Telenet BE, Sunrise CH, UPC SK, Virgin Media GB & IE, Ziggo NL)",
   "author": "Jochen Siegenthaler (https://github.com/jsiegenthaler/)",
-  "version": "2.4.0-beta.1",
+  "version": "2.4.0-beta.3",
   "platformname": "eosstb",
   "dependencies": {
     "axios": "^1.16.0",