homebridge-withings-environment-data 1.3.3 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [1.5.0] - 2026-08-19
+
+### Added
+- "Send Stale Data Notification" checkbox (default on): lets the ntfy
+  notification for stale data be turned off independently of the log
+  warning and "No Response" in the Home app, which still happen either way
+- Log line confirming a successful MQTT broker connection, and one per poll
+  reporting how many readings were published and over what time range
+  (previously only connection *errors* were logged, so a client that never
+  connected looked the same in the log as a working one)
+
+### Fixed
+- MQTT backfill no longer gets stuck once the newest known reading is
+  itself still stale by the time it's fetched (e.g. the scale recovers
+  from an outage, but the newest synced point is still older than the
+  Stale Data Warning Threshold). Publishing is now gated purely on
+  whether a reading has already been sent, not on wall-clock staleness
+- MQTT backfill no longer strands readings on the first run after
+  upgrading: the "last published" marker was seeded from the newest
+  reading the *poller* had seen rather than the newest actually
+  *published*, silently skipping everything in between
+
+## [1.4.0] - 2026-08-19
+
+### Added
+- `last_seen` field in the MQTT payload, reflecting the actual Withings
+  measurement time (not poll/publish time). Format configurable via a new
+  "Last Seen" dropdown: `ISO_8601` (default, UTC), `ISO_8601 local`,
+  `epoch` (milliseconds), or `disabled` to omit the field
+- MQTT publishing now backfills every reading the scale buffered since the
+  last publish, not just the single newest one, published oldest first
+
+### Changed
+- MQTT Retain is now on by default (previously off by default)
+
 ## [1.3.3] - 2026-08-04
 
 ### Fixed

package/README.md

@@ -1,4 +1,4 @@
-# Withings Environment Data v1.3.3
+# Withings Environment Data v1.5.0
 
 **This Homebridge plugin has been 100% vibe coded with Claude.**
 
@@ -54,12 +54,18 @@ turned on or off in Configuration:
 - **Expose sensors as HomeKit Accessories** (default on): when off, the
   plugin still polls Withings (and still publishes to MQTT, if enabled),
   but doesn't create or update any HomeKit accessory.
-- **Publish to MQTT** (default off): when on, every successful poll
-  publishes a message to topic `withingsenv/ws-50` on the configured
-  broker, shaped like `{"temperature": 25.2, "co2_levels": 674}`. Messages
-  aren't retained unless the Retain option is enabled. Publishing pauses
-  once the data is stale (see Stale Data Warning Threshold below) and
-  resumes once a fresh reading comes in.
+- **Publish to MQTT** (default off): when on, publishes a message to topic
+  `withingsenv/ws-50` on the configured broker, shaped like
+  `{"temperature": 25.2, "co2_levels": 674, "last_seen":
+  "2026-08-18T20:30:00.000Z"}`, for every reading buffered by the scale
+  since the last publish, not just the newest — the WS-50 can take several
+  readings internally before it syncs, and this backfills that gap instead
+  of collapsing it into one message. Each is published in the order it was
+  actually recorded, oldest first. Messages are retained by default.
+  Publishing only ever sends readings not already sent before (tracked
+  independently of HomeKit's staleness check below), so it keeps working
+  even if the newest available reading is itself still old by the time it
+  arrives.
 
 ### Configuration
 
@@ -87,16 +93,25 @@ Fields:
   Anything above the Inferior boundary is reported as Poor.
 - **Expose sensors as HomeKit Accessories**: see [Usage](#usage) above.
   Default on.
-- **Publish to MQTT / Host / Port / Username / Password / Retain**: see
-  [Usage](#usage) above. Publishing is off by default; Port defaults to
-  1883. Username/Password are optional, for brokers that require auth.
-  Retain is off by default.
+- **Publish to MQTT / Host / Port / Username / Password / Last Seen /
+  Retain**: see [Usage](#usage) above. Publishing is off by default; Port
+  defaults to 1883. Username/Password are optional, for brokers that
+  require auth. **Last Seen** controls the format of the `last_seen`
+  field, which always reflects the time the scale actually took the
+  measurement (not when the plugin polled or published it): `ISO_8601`
+  (default, UTC), `ISO_8601 local` (with UTC offset), `epoch`
+  (milliseconds), or `disabled` to omit the field entirely. Retain is on
+  by default.
 - **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.
+  poll for as long as it stays stale, and the sensors show "No Response" in
+  the Home app. Default 4. This is separate from poll failures.
+- **Send Stale Data Notification** (default on): whether a stale reading
+  additionally sends a single ntfy notification (requires ntfy.sh
+  Notification Topic below). The log warning and "No Response" in the Home
+  app happen either way, so turn this off if the unresponsive sensor is
+  signal enough on its own.
 - **ntfy.sh Notification 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

package/config.schema.json

@@ -106,6 +106,18 @@
           "type": "password"
         }
       },
+      "mqttLastSeen": {
+        "title": "Last Seen",
+        "type": "string",
+        "default": "ISO_8601",
+        "oneOf": [
+          { "title": "ISO_8601 (default)", "enum": ["ISO_8601"] },
+          { "title": "ISO_8601 local", "enum": ["ISO_8601_local"] },
+          { "title": "epoch (ms)", "enum": ["epoch"] },
+          { "title": "disabled", "enum": ["disable"] }
+        ],
+        "description": "Adds a last_seen field to the MQTT payload with the time of the newest Withings measurement (like zigbee2mqtt)."
+      },
       "mqttRetain": {
         "title": "Retain",
         "type": "boolean",
@@ -125,6 +137,11 @@
         "minimum": 1,
         "description": "If the newest CO2/temperature reading from the scale itself is older than this many hours, log a warning, show \"No Response\" in the Home app, and send a notification."
       },
+      "sendStaleDataNotification": {
+        "title": "Send Stale Data Notification",
+        "type": "boolean",
+        "description": "Send an ntfy notification when data goes stale (requires ntfy.sh Notification Topic below). The log warning and \"No Response\" in the Home app happen either way."
+      },
       "ntfyTopic": {
         "title": "ntfy.sh Notification Topic",
         "type": "string",
@@ -158,6 +175,7 @@
         "mqttPort",
         "mqttUsername",
         "mqttPassword",
+        "mqttLastSeen",
         "mqttRetain"
       ]
     },
@@ -177,6 +195,7 @@
     "pollIntervalMinutes",
     "noResponseAfterMissedPolls",
     "staleDataWarningThresholdHours",
+    "sendStaleDataNotification",
     "ntfyTopic"
   ]
 }

package/index.js

@@ -68,9 +68,27 @@ async function fetchLatest({ cookieHeader, sessionToken, deviceId, userId }) {
     // 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,
+    // Full backlog within the window (getmeashf — "high frequency measure"),
+    // not just the newest point — the scale can buffer multiple readings
+    // internally between cloud syncs. Only used for MQTT backfill; HomeKit
+    // characteristics only ever reflect the single newest point above.
+    co2Series,
+    tempSeries,
   };
 }
 
+// Local-time ISO 8601 with UTC offset — Date's own toISOString() is always UTC.
+function toLocalIso8601(date) {
+  const pad = (n) => String(Math.floor(Math.abs(n))).padStart(2, '0');
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+    `${sign}${pad(offsetMinutes / 60)}:${pad(offsetMinutes % 60)}`
+  );
+}
+
 function mapCo2ToAirQuality(ppm, AirQuality, thresholds) {
   if (ppm < thresholds.excellentMaxPpm) return AirQuality.EXCELLENT;
   if (ppm < thresholds.goodMaxPpm) return AirQuality.GOOD;
@@ -122,6 +140,19 @@ class WithingsEnvironmentDataPlatform {
     // 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;
+    // Unix seconds of the newest reading already published to MQTT, used to
+    // backfill any points buffered by the scale since the last publish rather
+    // than only ever sending the single newest one.
+    //
+    // Deliberately NOT seeded from lastReadingDate when absent: that tracks the
+    // newest reading the *poller* has seen, which is not the same as the newest
+    // reading actually *published*. Seeding from it silently strands everything
+    // in between (found live: ~12h of readings were skipped on upgrade because
+    // lastReadingDate had moved on while MQTT publishing was blocked). Starting
+    // at null instead republishes at most one window on first run, which the
+    // watermark then dedups from — failing toward a duplicate rather than
+    // toward permanent data loss.
+    this.lastPublishedMqttDate = state.lastPublishedMqttDate ?? 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
@@ -152,6 +183,7 @@ class WithingsEnvironmentDataPlatform {
         JSON.stringify({
           sessionKey: this.sessionKey,
           lastReadingDate: this.lastReadingDate,
+          lastPublishedMqttDate: this.lastPublishedMqttDate,
           staleNotifiedForReadingDate: this.staleNotifiedForReadingDate,
         })
       );
@@ -239,7 +271,10 @@ class WithingsEnvironmentDataPlatform {
       password: this.config.mqttPassword || undefined,
     });
     this.mqttClient.on('error', (err) => this.log.warn(`MQTT connection error: ${err.message}`));
-    if (this.config.mqttRetain !== true) {
+    // Without this, a silently-never-connecting client looks identical in the
+    // log to a working one, since only the error path said anything.
+    this.mqttClient.on('connect', () => this.log.info(`Connected to MQTT broker at ${url}.`));
+    if (this.config.mqttRetain === false) {
       // A publish with retain:false does NOT clear a previously-retained message —
       // the broker keeps serving the last retained one until something explicitly
       // clears it. Do that once per connect so turning Retain off actually stops
@@ -249,11 +284,86 @@ class WithingsEnvironmentDataPlatform {
     this.api.on('shutdown', () => this.mqttClient.end());
   }
 
-  publishMqttReading() {
+  // Config UI doesn't reliably apply schema defaults on boolean fields (see
+  // v1.3.2), so "on by default" is expressed here as "anything but an explicit
+  // false", not via a schema default.
+  getMqttRetain() {
+    return this.config.mqttRetain !== false;
+  }
+
+  getMqttLastSeenFormat() {
+    const valid = ['ISO_8601', 'ISO_8601_local', 'epoch', 'disable'];
+    return valid.includes(this.config.mqttLastSeen) ? this.config.mqttLastSeen : 'ISO_8601';
+  }
+
+  formatLastSeen(readingDateUnixSeconds) {
+    const format = this.getMqttLastSeenFormat();
+    if (format === 'disable' || readingDateUnixSeconds === null || readingDateUnixSeconds === undefined) {
+      return undefined;
+    }
+
+    const date = new Date(readingDateUnixSeconds * 1000);
+    if (format === 'epoch') return date.getTime();
+    if (format === 'ISO_8601_local') return toLocalIso8601(date);
+    return date.toISOString();
+  }
+
+  // Publishes every buffered point newer than the last one we published, oldest
+  // first, instead of only ever the single newest — so a gap where the scale
+  // synced a backlog of readings (e.g. after being offline) gets backfilled on
+  // the MQTT side rather than collapsed into one message. HomeKit is
+  // unaffected: it only ever shows the single newest value (see applyReading).
+  //
+  // Deliberately NOT gated on isDataStale(): that reflects whether the newest
+  // known reading is old relative to *now*, which can still be true right
+  // after a real recovery (e.g. the scale's own buffered backlog syncs, but
+  // its newest point is still older than the threshold). Gating on that would
+  // strand genuinely new, never-before-published backlog until an even
+  // fresher point arrives later. Dedup below (lastPublishedMqttDate) already
+  // prevents ever republishing the same reading, which is the only thing this
+  // gate needs to guard against.
+  publishMqttReadings(co2Series, tempSeries) {
     if (!this.mqttClient) return;
-    if (this.isDataStale()) return;
-    const payload = JSON.stringify({ temperature: this.lastReading.temperature, co2_levels: this.lastReading.co2 });
-    this.mqttClient.publish(MQTT_TOPIC, payload, { retain: this.config.mqttRetain === true });
+
+    const byDate = new Map();
+    for (const point of co2Series) {
+      if (!byDate.has(point.date)) byDate.set(point.date, {});
+      byDate.get(point.date).co2 = point.value;
+    }
+    for (const point of tempSeries) {
+      if (!byDate.has(point.date)) byDate.set(point.date, {});
+      byDate.get(point.date).temperature = point.value;
+    }
+
+    const unpublished = [...byDate.entries()]
+      .filter(([date]) => this.lastPublishedMqttDate === null || date > this.lastPublishedMqttDate)
+      .sort(([a], [b]) => a - b);
+
+    for (const [date, reading] of unpublished) {
+      const payload = {};
+      if (reading.co2 !== undefined) payload.co2_levels = reading.co2;
+      if (reading.temperature !== undefined) payload.temperature = reading.temperature;
+      // The actual Withings measurement time, not when this poll ran or published.
+      const lastSeen = this.formatLastSeen(date);
+      if (lastSeen !== undefined) payload.last_seen = lastSeen;
+      this.mqttClient.publish(MQTT_TOPIC, JSON.stringify(payload), { retain: this.getMqttRetain() });
+      this.lastPublishedMqttDate = date;
+    }
+
+    if (unpublished.length > 0) {
+      this.persistState();
+      const first = this.formatStaleDateTime(unpublished[0][0]);
+      const last = this.formatStaleDateTime(unpublished[unpublished.length - 1][0]);
+      const range =
+        unpublished.length === 1
+          ? `${first.date} ${first.time}`
+          : `${first.date} ${first.time} to ${last.date} ${last.time}`;
+      this.log.info(`Published ${unpublished.length} reading(s) to MQTT (${range}).`);
+    } else {
+      // Distinguishes "nothing new to send" from "never connected/never tried",
+      // which otherwise look the same from the log alone.
+      this.log.debug('No new readings to publish to MQTT; nothing newer than the last published reading.');
+    }
   }
 
   setupServices(accessory) {
@@ -319,14 +429,14 @@ class WithingsEnvironmentDataPlatform {
         }
       }
 
-      const { co2, temperature, readingDate } = await fetchLatest({
+      const { co2, temperature, readingDate, co2Series, tempSeries } = await fetchLatest({
         cookieHeader,
         sessionToken,
         deviceId: this.deviceId,
         userId: this.userId,
       });
 
-      this.applyReading(co2, temperature, readingDate);
+      this.applyReading(co2, temperature, readingDate, co2Series, tempSeries);
       this.setFault(false);
       this.missedCycles = 0;
       this.hasNotifiedFailure = false;
@@ -404,6 +514,12 @@ class WithingsEnvironmentDataPlatform {
     };
   }
 
+  // Same Config UI boolean-default rendering quirk as mqttRetain (see
+  // getMqttRetain), so "on by default" is a runtime default, not a schema one.
+  getSendStaleDataNotification() {
+    return this.config.sendStaleDataNotification !== false;
+  }
+
   getStaleDataThresholdHours() {
     const threshold = Number(this.config.staleDataWarningThresholdHours);
     return Number.isFinite(threshold) && threshold >= 1 ? threshold : 4;
@@ -437,10 +553,12 @@ class WithingsEnvironmentDataPlatform {
       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'
-        );
+        if (this.getSendStaleDataNotification()) {
+          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;
@@ -481,7 +599,7 @@ class WithingsEnvironmentDataPlatform {
     return this.lastReading.temperature;
   }
 
-  applyReading(co2, temperature, readingDate) {
+  applyReading(co2, temperature, readingDate, co2Series = [], tempSeries = []) {
     const co2Threshold = this.getCo2Threshold();
     const hasReading = (co2 !== null && co2 !== undefined) || (temperature !== null && temperature !== undefined);
 
@@ -526,7 +644,7 @@ class WithingsEnvironmentDataPlatform {
     }
 
     if (hasReading) {
-      this.publishMqttReading();
+      this.publishMqttReadings(co2Series, tempSeries);
     }
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-withings-environment-data",
   "displayName": "Withings Environment Data",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "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": [