homebridge-withings-environment-data 1.1.2 → 1.2.1

package/CHANGELOG.md

@@ -6,6 +6,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [1.2.1] - 2026-08-02
+
+### Changed
+- The stale-data log warning now logs on every poll while data remains
+  stale (matching how missed poll cycles are already logged), instead of
+  only once per stale streak.
+
+### Fixed
+- The stale-data ntfy notification no longer re-fires every time
+  Homebridge restarts while the same stale reading is still the newest one
+  on record. The "already notified about this" state, and the last-known
+  reading date it applies to, are now both persisted to disk instead of
+  living only in memory (a first fix persisted only the former, which
+  still misfired if the first poll after a restart happened to fail), and
+  still reset correctly once a fresher reading comes in.
+
+## [1.2.0] - 2026-07-31
+
+### Added
+- Stale data detection: if the newest reading from the scale itself is
+  older than the new `staleDataWarningThresholdHours` config field
+  (default 4 hours), a warning is logged with the last-recorded date and
+  time, the sensors report "No Response" in the Home app, and (if `ntfy
+  Topic` is set) a notification is sent — all once per stale streak, with
+  a log line and reset once a fresher reading comes in. Separate from
+  poll failures, which were already covered.
+
 ## [1.1.2] - 2026-07-28
 
 ### Added

package/README.md

@@ -1,4 +1,4 @@
-# Homebridge Withings Environment Data v1.1.2
+# Homebridge Withings Environment Data v1.2.1
 
 **This Homebridge plugin has been 100% vibe coded with Claude.**
 
@@ -72,11 +72,18 @@ Fields:
 - **Air Quality: Excellent/Good/Fair/Inferior below (ppm)**: the four ppm
   boundaries the AirQualitySensor category is based on (defaults 800, 1000,
   1500, 2000).
+- **Stale Data Warning Threshold (hours)**: if the newest reading from the
+  scale itself (not the plugin's poll) is older than this many hours — e.g.
+  nobody's stood on the scale in a while — a warning is logged on every
+  poll for as long as it stays stale, the sensors show "No Response" in the
+  Home app, and (if ntfy Topic is set) a single notification is sent for
+  that stale reading. Default 4. This is separate from poll failures.
 - **ntfy Topic (optional)**: if set, sends a push notification via
   [ntfy.sh](https://ntfy.sh) to this topic the first time a poll fails
   (not repeated on every subsequent failure in the same streak; only once
   a poll succeeds again does the next failure trigger a fresh
-  notification). Leave blank to disable.
+  notification), and separately, once when the data becomes stale (see
+  above). Leave blank to disable.
 
 ### How authentication works
 

package/config.schema.json

@@ -84,6 +84,13 @@
         "minimum": 0,
         "description": "Consecutive failed polls to tolerate (keeping the last known readings) before the Home app shows \"No Response\". 0 means show it immediately on any failure."
       },
+      "staleDataWarningThresholdHours": {
+        "title": "Stale Data Warning Threshold (hours)",
+        "type": "integer",
+        "default": 4,
+        "minimum": 1,
+        "description": "If the newest CO2/temperature reading from the scale itself is older than this many hours (e.g. nobody's stood on it), log a warning, show \"No Response\" in the Home app, and (if ntfy Topic is set) send a notification. This is separate from poll failures above."
+      },
       "ntfyTopic": {
         "title": "ntfy Topic (optional)",
         "type": "string",

package/index.js

@@ -55,11 +55,17 @@ async function fetchLatest({ cookieHeader, sessionToken, deviceId, userId }) {
 
   const co2Series = json.body.series?.find((s) => s.type === MEASTYPE_CO2)?.data ?? [];
   const tempSeries = json.body.series?.find((s) => s.type === MEASTYPE_TEMPERATURE)?.data ?? [];
+  // Both series are newest-first, so the first entry is the latest reading.
+  const co2Point = co2Series.length > 0 ? co2Series[0] : null;
+  const tempPoint = tempSeries.length > 0 ? tempSeries[0] : null;
 
   return {
-    // Both series are newest-first, so the first entry is the latest reading.
-    co2: co2Series.length > 0 ? co2Series[0].value : null,
-    temperature: tempSeries.length > 0 ? tempSeries[0].value : null,
+    co2: co2Point ? co2Point.value : null,
+    temperature: tempPoint ? tempPoint.value : null,
+    // Unix seconds the reading was actually taken, not when we fetched it —
+    // used to detect the scale itself going quiet (e.g. nobody's stood on
+    // it in a while), as opposed to the plugin failing to reach Withings.
+    readingDate: co2Point?.date ?? tempPoint?.date ?? null,
   };
 }
 
@@ -97,32 +103,56 @@ class WithingsEnvironmentDataPlatform {
     // missed poll — reset once a poll succeeds again.
     this.hasNotifiedFailure = false;
 
+    this.warnedMissingReadingDate = false;
+
     // The long-lived (~1 week) session_key that lets us skip email/password/2FA
     // entirely on most polls — see lib/login.js's resumeSession(). Persisted to
     // disk so it survives Homebridge restarts, and only a full login() refreshes
     // it, since repeatedly hitting the password endpoint appears to be heavily
     // throttled by Withings.
     this.sessionStatePath = path.join(this.api.user.storagePath(), SESSION_STATE_FILENAME);
-    this.sessionKey = this.loadSessionKey();
+    const state = this.loadPersistedState();
+    this.sessionKey = state.sessionKey ?? null;
+    // Unix seconds of the newest reading actually seen so far (from the Withings
+    // measurement itself, not from a successful poll) — used to detect the scale
+    // going quiet rather than the plugin failing to poll. Persisted and restored
+    // immediately on boot (rather than waiting on the first poll to repopulate
+    // it) so a restart can't be mistaken for "no reading yet" and wrongly clear
+    // an active stale-warning below.
+    this.lastReadingDate = state.lastReadingDate ?? null;
+    // The readingDate (unix seconds) we last sent a stale-data *notification* for,
+    // or null if not currently in a notified state. The log warning itself repeats
+    // every poll while data stays stale (like missed-poll-cycle failures do), but
+    // this gates the ntfy notification to once per distinct stale reading, and is
+    // persisted so a Homebridge restart doesn't re-notify about a reading we've
+    // already notified about — it only resets once a fresher reading comes in.
+    this.staleNotifiedForReadingDate = state.staleNotifiedForReadingDate ?? null;
 
     this.api.on('didFinishLaunching', () => this.discoverDevices());
   }
 
-  loadSessionKey() {
+  loadPersistedState() {
     try {
       const raw = fs.readFileSync(this.sessionStatePath, 'utf8');
-      return JSON.parse(raw).sessionKey ?? null;
+      return JSON.parse(raw);
     } catch (err) {
       if (err.code !== 'ENOENT') {
         this.log.warn(`Could not read session state file: ${err.message}`);
       }
-      return null;
+      return {};
     }
   }
 
-  saveSessionKey(sessionKey) {
+  persistState() {
     try {
-      fs.writeFileSync(this.sessionStatePath, JSON.stringify({ sessionKey }));
+      fs.writeFileSync(
+        this.sessionStatePath,
+        JSON.stringify({
+          sessionKey: this.sessionKey,
+          lastReadingDate: this.lastReadingDate,
+          staleNotifiedForReadingDate: this.staleNotifiedForReadingDate,
+        })
+      );
     } catch (err) {
       this.log.warn(`Could not persist session state file: ${err.message}`);
     }
@@ -147,7 +177,7 @@ class WithingsEnvironmentDataPlatform {
     if (result.sessionKey) {
       if (result.sessionKey !== this.sessionKey) {
         this.sessionKey = result.sessionKey;
-        this.saveSessionKey(result.sessionKey);
+        this.persistState();
         this.log.info('Withings full login succeeded; cached the new session for future polls.');
       } else {
         this.log.info('Withings full login succeeded; session token unchanged.');
@@ -240,14 +270,14 @@ class WithingsEnvironmentDataPlatform {
         }
       }
 
-      const { co2, temperature } = await fetchLatest({
+      const { co2, temperature, readingDate } = await fetchLatest({
         cookieHeader,
         sessionToken,
         deviceId: this.deviceId,
         userId: this.userId,
       });
 
-      this.applyReading(co2, temperature);
+      this.applyReading(co2, temperature, readingDate);
       this.setFault(false);
       this.missedCycles = 0;
       this.hasNotifiedFailure = false;
@@ -270,17 +300,22 @@ class WithingsEnvironmentDataPlatform {
         await this.sendNtfyNotification(notificationMessage);
       }
     }
+
+    // Independent of whether this poll itself succeeded — the scale can go
+    // quiet (no one's stood on it) while polls keep succeeding fine, so this
+    // is checked every cycle against whatever the newest reading actually is.
+    await this.checkStaleData();
   }
 
-  async sendNtfyNotification(errorMessage) {
+  async sendNtfyNotification(message, title = 'Homebridge: Getting Withings Environment Data Failed!') {
     const topic = this.config.ntfyTopic;
     if (!topic) return;
 
     try {
       await fetch(`https://ntfy.sh/${encodeURIComponent(topic)}`, {
         method: 'POST',
-        headers: { Title: 'Homebridge: Getting Withings Environment Data Failed!' },
-        body: errorMessage,
+        headers: { Title: title },
+        body: message,
       });
     } catch (err) {
       this.log.warn(`Failed to send ntfy notification: ${err.message}`);
@@ -310,8 +345,53 @@ class WithingsEnvironmentDataPlatform {
     };
   }
 
+  getStaleDataThresholdHours() {
+    const threshold = Number(this.config.staleDataWarningThresholdHours);
+    return Number.isFinite(threshold) && threshold >= 1 ? threshold : 4;
+  }
+
+  // dd-mm and 24hr time, per the configured warning's required format — no
+  // year, since this is about "how long ago", not a historical record.
+  formatStaleDateTime(unixSeconds) {
+    const d = new Date(unixSeconds * 1000);
+    const pad = (n) => String(n).padStart(2, '0');
+    return {
+      date: `${pad(d.getDate())}-${pad(d.getMonth() + 1)}`,
+      time: `${pad(d.getHours())}:${pad(d.getMinutes())}`,
+    };
+  }
+
+  isDataStale() {
+    if (!this.lastReadingDate) return false;
+    const ageHours = (Date.now() / 1000 - this.lastReadingDate) / 3600;
+    return ageHours > this.getStaleDataThresholdHours();
+  }
+
+  async checkStaleData() {
+    const stale = this.isDataStale();
+
+    if (stale) {
+      const { date, time } = this.formatStaleDateTime(this.lastReadingDate);
+      this.log.warn(`Withings data is stale: last recorded at ${date} ${time}`);
+
+      const alreadyNotifiedForThisReading = this.staleNotifiedForReadingDate === this.lastReadingDate;
+      if (!alreadyNotifiedForThisReading) {
+        this.staleNotifiedForReadingDate = this.lastReadingDate;
+        this.persistState();
+        await this.sendNtfyNotification(
+          `Temperature and/or CO2 readings haven't been updated since ${date} at ${time}.`,
+          'Homebridge: Withings Environment Data is out of date'
+        );
+      }
+    } else if (this.staleNotifiedForReadingDate !== null) {
+      this.staleNotifiedForReadingDate = null;
+      this.persistState();
+      this.log.info('Withings: fresh data has been recorded.');
+    }
+  }
+
   isStale() {
-    return !this.hasEverSucceeded || this.missedCycles > this.getNoResponseThreshold();
+    return !this.hasEverSucceeded || this.missedCycles > this.getNoResponseThreshold() || this.isDataStale();
   }
 
   throwIfStale() {
@@ -342,8 +422,21 @@ class WithingsEnvironmentDataPlatform {
     return this.lastReading.temperature;
   }
 
-  applyReading(co2, temperature) {
+  applyReading(co2, temperature, readingDate) {
     const co2Threshold = this.getCo2Threshold();
+    const hasReading = (co2 !== null && co2 !== undefined) || (temperature !== null && temperature !== undefined);
+
+    if (hasReading && (readingDate === null || readingDate === undefined)) {
+      if (!this.warnedMissingReadingDate) {
+        this.warnedMissingReadingDate = true;
+        this.log.warn(
+          'Withings measurement data has no recognizable date field; stale data detection is disabled until this is fixed.'
+        );
+      }
+    } else if (readingDate !== null && readingDate !== undefined && readingDate !== this.lastReadingDate) {
+      this.lastReadingDate = readingDate;
+      this.persistState();
+    }
 
     if (co2 !== null && co2 !== undefined) {
       this.lastReading.co2 = co2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-withings-environment-data",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "Homebridge plugin exposing ambient CO2/air-quality and room temperature readings from a Withings WS-50 scale as HomeKit sensors",
   "main": "index.js",
   "files": [