homebridge-withings-environment-data 1.4.0 → 1.6.1

package/CHANGELOG.md

@@ -6,6 +6,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [1.6.1] - 2026-08-21
+
+### Fixed
+- Publish workflow's CI Node version bumped to 22 — the first real run
+  failed at `npm install -g npm@latest`, since the latest npm now
+  requires Node `^22.22.2 || ^24.15.0 || >=26.0.0` and the workflow had
+  pinned Node 20
+
+## [1.6.0] - 2026-08-21
+
+### Added
+- "Requires authentication" checkbox in the MQTT fieldset; Username and
+  Password only appear (and are only sent to the broker) when it's checked
+
+### Changed
+- MQTT Host and Port merged into a single "Host" field including the port,
+  e.g. `localhost:1883` (the new default)
+- Publishing to npm now happens automatically via GitHub Actions on tagged
+  releases, using npm's OIDC trusted publishing (no npm tokens in CI)
+
+## [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

package/README.md

@@ -1,4 +1,4 @@
-# Withings Environment Data v1.4.0
+# Withings Environment Data v1.6.1
 
 **This Homebridge plugin has been 100% vibe coded with Claude.**
 
@@ -62,9 +62,10 @@ turned on or off in Configuration:
   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 pauses entirely once the newest known reading is stale (see
-  Stale Data Warning Threshold below) and resumes (with any accumulated
-  backlog) once a fresh reading comes in.
+  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
 
@@ -92,21 +93,26 @@ 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 / 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.
+- **Publish to MQTT / Host / Requires authentication / Username / Password /
+  Last Seen / Retain**: see [Usage](#usage) above. Publishing is off by
+  default. **Host** includes the port, e.g. `localhost:1883` (the
+  default). Username/Password only apply, and only appear, when
+  **Requires authentication** is checked. **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

@@ -87,13 +87,12 @@
       "mqttHost": {
         "title": "Host",
         "type": "string",
-        "default": "localhost",
-        "description": "Broker hostname or IP address."
+        "default": "localhost:1883",
+        "description": "Broker hostname or IP address, including port."
       },
-      "mqttPort": {
-        "title": "Port",
-        "type": "integer",
-        "default": 1883
+      "mqttRequiresAuth": {
+        "title": "Requires authentication",
+        "type": "boolean"
       },
       "mqttUsername": {
         "title": "Username",
@@ -137,6 +136,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",
@@ -167,9 +171,19 @@
       "items": [
         "publishToMqtt",
         "mqttHost",
-        "mqttPort",
-        "mqttUsername",
-        "mqttPassword",
+        "mqttRequiresAuth",
+        {
+          "key": "mqttUsername",
+          "condition": {
+            "functionBody": "return model.mqttRequiresAuth === true;"
+          }
+        },
+        {
+          "key": "mqttPassword",
+          "condition": {
+            "functionBody": "return model.mqttRequiresAuth === true;"
+          }
+        },
         "mqttLastSeen",
         "mqttRetain"
       ]
@@ -190,6 +204,7 @@
     "pollIntervalMinutes",
     "noResponseAfterMissedPolls",
     "staleDataWarningThresholdHours",
+    "sendStaleDataNotification",
     "ntfyTopic"
   ]
 }

package/index.js

@@ -142,11 +142,17 @@ class WithingsEnvironmentDataPlatform {
     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. Defaults to the already-
-    // known lastReadingDate (if any) on first boot after upgrading to this
-    // feature, so existing installs don't replay their entire pre-existing
-    // history — only genuinely new backlog from here on.
-    this.lastPublishedMqttDate = state.lastPublishedMqttDate ?? state.lastReadingDate ?? null;
+    // 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
@@ -250,21 +256,43 @@ class WithingsEnvironmentDataPlatform {
     return this.config.publishToMqtt === true;
   }
 
+  // mqttHost is a single "host[:port]" field; older configs saved before that
+  // merge may still have a separate mqttPort value sitting in config.json
+  // (config UI stops writing it once resaved, but doesn't retroactively
+  // delete it), so fall back to that before the hardcoded default.
+  getMqttHostAndPort() {
+    const raw = this.config.mqttHost || '';
+    const colonIndex = raw.lastIndexOf(':');
+    if (colonIndex > -1) {
+      const host = raw.slice(0, colonIndex);
+      const port = Number(raw.slice(colonIndex + 1));
+      if (host && Number.isFinite(port) && port > 0) {
+        return { host, port };
+      }
+    }
+    const legacyPort = Number(this.config.mqttPort);
+    return { host: raw, port: Number.isFinite(legacyPort) && legacyPort > 0 ? legacyPort : 1883 };
+  }
+
   connectMqtt() {
     if (!this.getPublishToMqtt()) return;
 
-    if (!this.config.mqttHost) {
+    const { host, port } = this.getMqttHostAndPort();
+    if (!host) {
       this.log.warn('Publish to MQTT is enabled but no MQTT Host is configured; MQTT publishing is disabled.');
       return;
     }
 
-    const port = Number(this.config.mqttPort);
-    const url = `mqtt://${this.config.mqttHost}:${Number.isFinite(port) && port > 0 ? port : 1883}`;
+    const url = `mqtt://${host}:${port}`;
+    const requiresAuth = this.config.mqttRequiresAuth === true;
     this.mqttClient = mqtt.connect(url, {
-      username: this.config.mqttUsername || undefined,
-      password: this.config.mqttPassword || undefined,
+      username: requiresAuth ? this.config.mqttUsername || undefined : undefined,
+      password: requiresAuth ? this.config.mqttPassword || undefined : undefined,
     });
     this.mqttClient.on('error', (err) => this.log.warn(`MQTT connection error: ${err.message}`));
+    // 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
@@ -304,9 +332,17 @@ class WithingsEnvironmentDataPlatform {
   // 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 byDate = new Map();
     for (const point of co2Series) {
@@ -335,6 +371,17 @@ class WithingsEnvironmentDataPlatform {
 
     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.');
     }
   }
 
@@ -486,6 +533,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;
@@ -519,10 +572,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;

package/package.json

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