homebridge-withings-environment-data 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [1.3.0] - 2026-08-03
+
+### Added
+- Optional MQTT publishing: when "Publish to MQTT" is enabled and a broker
+  Host is configured, every successful poll publishes a retained message
+  to topic `withingsenv/ws-50` shaped like
+  `{"temperature": 25.2, "co2_levels": 674}`
+- "Expose sensors as HomeKit Accessories" toggle (default on): when off,
+  the plugin still polls (and still publishes to MQTT, if enabled) but
+  doesn't create or update a HomeKit accessory
+
+### Changed
+- Config UI reorganized: Name, then an expanded "Authentication" fieldset,
+  the Expose/Publish checkboxes, a collapsed "MQTT" fieldset, a collapsed
+  "Air Quality" fieldset (shorter field titles, fewer descriptions), Poll
+  Interval, No Response After Missed Polls, Stale Data Warning Threshold,
+  ntfy.sh Notification Topic (renamed from "ntfy Topic (optional)")
+- `displayName` set in `package.json` so Homebridge Config UI shows
+  "Withings Environment Data" in the Plugins list instead of the raw npm
+  package name
+- Shortened a few config field descriptions (No Response After Missed
+  Polls, Stale Data Warning Threshold, ntfy.sh Notification Topic)
+
+## [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

package/README.md

@@ -1,4 +1,4 @@
-# Homebridge Withings Environment Data v1.2.0
+# Withings Environment Data v1.3.0
 
 **This Homebridge plugin has been 100% vibe coded with Claude.**
 
@@ -48,6 +48,17 @@ accessory:
 These appear automatically in the Home app after Homebridge restarts, no
 further setup needed. Readings update on the poll interval set below.
 
+HomeKit exposure and MQTT publishing are independent and can each be
+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 retained message to topic `withingsenv/ws-50` on the
+  configured broker, shaped like
+  `{"temperature": 25.2, "co2_levels": 674}`.
+
 ### Configuration
 
 All settings are entered through the Homebridge Config UI (Plugins tab,
@@ -69,15 +80,21 @@ Fields:
   matching the scale's own upload cadence).
 - **CO2 Detected Threshold (ppm)**: ppm above which the CarbonDioxideSensor
   reports "abnormal" (default 1000).
-- **Air Quality: Excellent/Good/Fair/Inferior below (ppm)**: the four ppm
-  boundaries the AirQualitySensor category is based on (defaults 800, 1000,
-  1500, 2000).
+- **Excellent/Good/Fair/Inferior below (ppm)**: the four ppm boundaries the
+  AirQualitySensor category is based on (defaults 800, 1000, 1500, 2000).
+  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**: see
+  [Usage](#usage) above. Publishing is off by default; Port defaults to
+  1883. Username/Password are optional, for brokers that require auth.
 - **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, the sensors
-  show "No Response" in the Home app, and (if ntfy Topic is set) a
-  notification is sent. Default 4. This is separate from poll failures.
-- **ntfy Topic (optional)**: if set, sends a push notification via
+  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.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
   a poll succeeds again does the next failure trigger a fresh

package/config.schema.json

@@ -12,6 +12,43 @@
         "default": "Withings Environment",
         "required": true
       },
+      "co2DetectedThresholdPpm": {
+        "title": "CO2 Detected Threshold (ppm)",
+        "type": "integer",
+        "default": 1000,
+        "minimum": 400
+      },
+      "airQualityExcellentMaxPpm": {
+        "title": "Excellent below (ppm)",
+        "type": "integer",
+        "default": 800,
+        "minimum": 1
+      },
+      "airQualityGoodMaxPpm": {
+        "title": "Good below (ppm)",
+        "type": "integer",
+        "default": 1000,
+        "minimum": 1
+      },
+      "airQualityFairMaxPpm": {
+        "title": "Fair below (ppm)",
+        "type": "integer",
+        "default": 1500,
+        "minimum": 1
+      },
+      "airQualityInferiorMaxPpm": {
+        "title": "Inferior below (ppm)",
+        "type": "integer",
+        "default": 2000,
+        "minimum": 1,
+        "description": "Anything above is reported as Poor."
+      },
+      "pollIntervalMinutes": {
+        "title": "Poll Interval (minutes)",
+        "type": "integer",
+        "default": 30,
+        "minimum": 5
+      },
       "email": {
         "title": "Withings Email",
         "type": "string",
@@ -37,65 +74,103 @@
         "required": true,
         "description": "The value of that same 2fa_token_<hash> cookie"
       },
-      "pollIntervalMinutes": {
-        "title": "Poll Interval (minutes)",
-        "type": "integer",
-        "default": 30,
-        "minimum": 5
+      "exposeAsHomekitAccessories": {
+        "title": "Expose sensors as HomeKit Accessories",
+        "type": "boolean",
+        "default": true
       },
-      "co2DetectedThresholdPpm": {
-        "title": "CO2 Detected Threshold (ppm)",
-        "type": "integer",
-        "default": 1000,
-        "minimum": 400
+      "publishToMqtt": {
+        "title": "Publish to MQTT",
+        "type": "boolean",
+        "default": false,
+        "description": "Publish sensor data to configured MQTT broker. Topic name: \"withingsenv/ws-50\""
       },
-      "airQualityExcellentMaxPpm": {
-        "title": "Air Quality: Excellent below (ppm)",
-        "type": "integer",
-        "default": 800,
-        "minimum": 1,
-        "description": "CO2 readings below this are reported as Excellent air quality."
+      "mqttHost": {
+        "title": "Host",
+        "type": "string",
+        "description": "Broker hostname or IP address."
       },
-      "airQualityGoodMaxPpm": {
-        "title": "Air Quality: Good below (ppm)",
+      "mqttPort": {
+        "title": "Port",
         "type": "integer",
-        "default": 1000,
-        "minimum": 1,
-        "description": "CO2 readings below this are reported as Good."
+        "default": 1883
       },
-      "airQualityFairMaxPpm": {
-        "title": "Air Quality: Fair below (ppm)",
-        "type": "integer",
-        "default": 1500,
-        "minimum": 1,
-        "description": "CO2 readings below this are reported as Fair."
+      "mqttUsername": {
+        "title": "Username",
+        "type": "string"
       },
-      "airQualityInferiorMaxPpm": {
-        "title": "Air Quality: Inferior below (ppm)",
-        "type": "integer",
-        "default": 2000,
-        "minimum": 1,
-        "description": "CO2 readings below this are reported as Inferior. Anything above is reported as Poor."
+      "mqttPassword": {
+        "title": "Password",
+        "type": "string",
+        "x-schema-form": {
+          "type": "password"
+        }
       },
       "noResponseAfterMissedPolls": {
         "title": "No Response After Missed Polls",
         "type": "integer",
         "default": 2,
         "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."
+        "description": "Consecutive failed polls to tolerate before the Home app shows \"No Response\"."
       },
       "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."
+        "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."
       },
       "ntfyTopic": {
-        "title": "ntfy Topic (optional)",
+        "title": "ntfy.sh Notification Topic",
         "type": "string",
-        "description": "If set, sends a push notification via ntfy.sh to this topic the first time a poll fails (not repeated on every subsequent failure in the same streak). Leave blank to disable."
+        "description": "If set, sends a push notification via ntfy.sh the first time a poll fails."
       }
     }
-  }
+  },
+  "layout": [
+    "name",
+    {
+      "type": "fieldset",
+      "title": "Authentication",
+      "expandable": true,
+      "expanded": true,
+      "items": [
+        "email",
+        "password",
+        "trustCookieName",
+        "trustCookieValue"
+      ]
+    },
+    "exposeAsHomekitAccessories",
+    "publishToMqtt",
+    {
+      "type": "fieldset",
+      "title": "MQTT",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "mqttHost",
+        "mqttPort",
+        "mqttUsername",
+        "mqttPassword"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Air Quality",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "co2DetectedThresholdPpm",
+        "airQualityExcellentMaxPpm",
+        "airQualityGoodMaxPpm",
+        "airQualityFairMaxPpm",
+        "airQualityInferiorMaxPpm"
+      ]
+    },
+    "pollIntervalMinutes",
+    "noResponseAfterMissedPolls",
+    "staleDataWarningThresholdHours",
+    "ntfyTopic"
+  ]
 }

package/index.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const mqtt = require('mqtt');
 const { login, resumeSession } = require('./lib/login');
 const { discoverDevice } = require('./lib/discover');
 
@@ -16,6 +17,7 @@ const APPPFM = 'web';
 const WINDOW_HOURS = 48;
 
 const PLATFORM_NAME = 'WithingsEnvironmentData';
+const MQTT_TOPIC = 'withingsenv/ws-50';
 
 async function fetchLatest({ cookieHeader, sessionToken, deviceId, userId }) {
   const enddate = Math.floor(Date.now() / 1000);
@@ -103,12 +105,6 @@ class WithingsEnvironmentDataPlatform {
     // missed poll — reset once a poll succeeds again.
     this.hasNotifiedFailure = false;
 
-    // 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.
-    // Warn/notify once per stale streak, reset once a fresher reading comes in.
-    this.lastReadingDate = null;
-    this.staleDataWarned = false;
     this.warnedMissingReadingDate = false;
 
     // The long-lived (~1 week) session_key that lets us skip email/password/2FA
@@ -117,26 +113,48 @@ class WithingsEnvironmentDataPlatform {
     // 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}`);
     }
@@ -161,7 +179,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.');
@@ -182,15 +200,54 @@ class WithingsEnvironmentDataPlatform {
     const uuid = this.api.hap.uuid.generate('withings-environment-data');
     let accessory = this.accessories.find((acc) => acc.UUID === uuid);
 
-    if (!accessory) {
-      accessory = new this.api.platformAccessory(this.config.name || 'Withings Environment', uuid);
-      this.api.registerPlatformAccessories('homebridge-withings-environment-data', PLATFORM_NAME, [accessory]);
+    if (this.getExposeAsHomekitAccessories()) {
+      if (!accessory) {
+        accessory = new this.api.platformAccessory(this.config.name || 'Withings Environment', uuid);
+        this.api.registerPlatformAccessories('homebridge-withings-environment-data', PLATFORM_NAME, [accessory]);
+      }
+      this.setupServices(accessory);
+    } else if (accessory) {
+      // Previously exposed, now toggled off — remove the stale accessory rather
+      // than leaving it registered but never updated.
+      this.api.unregisterPlatformAccessories('homebridge-withings-environment-data', PLATFORM_NAME, [accessory]);
     }
 
-    this.setupServices(accessory);
+    this.connectMqtt();
     this.startPolling();
   }
 
+  getExposeAsHomekitAccessories() {
+    return this.config.exposeAsHomekitAccessories !== false;
+  }
+
+  getPublishToMqtt() {
+    return this.config.publishToMqtt === true;
+  }
+
+  connectMqtt() {
+    if (!this.getPublishToMqtt()) return;
+
+    if (!this.config.mqttHost) {
+      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}`;
+    this.mqttClient = mqtt.connect(url, {
+      username: this.config.mqttUsername || undefined,
+      password: this.config.mqttPassword || undefined,
+    });
+    this.mqttClient.on('error', (err) => this.log.warn(`MQTT connection error: ${err.message}`));
+    this.api.on('shutdown', () => this.mqttClient.end());
+  }
+
+  publishMqttReading() {
+    if (!this.mqttClient) return;
+    const payload = JSON.stringify({ temperature: this.lastReading.temperature, co2_levels: this.lastReading.co2 });
+    this.mqttClient.publish(MQTT_TOPIC, payload, { retain: true });
+  }
+
   setupServices(accessory) {
     this.infoService = accessory.getService(this.Service.AccessoryInformation);
     if (this.infoService) {
@@ -354,16 +411,22 @@ class WithingsEnvironmentDataPlatform {
   async checkStaleData() {
     const stale = this.isDataStale();
 
-    if (stale && !this.staleDataWarned) {
-      this.staleDataWarned = true;
+    if (stale) {
       const { date, time } = this.formatStaleDateTime(this.lastReadingDate);
       this.log.warn(`Withings data is stale: last recorded at ${date} ${time}`);
-      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 (!stale && this.staleDataWarned) {
-      this.staleDataWarned = false;
+
+      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.');
     }
   }
@@ -411,34 +474,47 @@ class WithingsEnvironmentDataPlatform {
           'Withings measurement data has no recognizable date field; stale data detection is disabled until this is fixed.'
         );
       }
-    } else if (readingDate !== null && readingDate !== undefined) {
+    } else if (readingDate !== null && readingDate !== undefined && readingDate !== this.lastReadingDate) {
       this.lastReadingDate = readingDate;
+      this.persistState();
     }
 
     if (co2 !== null && co2 !== undefined) {
       this.lastReading.co2 = co2;
       this.hasEverSucceeded = true;
-      this.co2Service.updateCharacteristic(this.Characteristic.CarbonDioxideLevel, co2);
-      this.co2Service.updateCharacteristic(
-        this.Characteristic.CarbonDioxideDetected,
-        co2 > co2Threshold
-          ? this.Characteristic.CarbonDioxideDetected.CO2_LEVELS_ABNORMAL
-          : this.Characteristic.CarbonDioxideDetected.CO2_LEVELS_NORMAL
-      );
-      this.airQualityService.updateCharacteristic(
-        this.Characteristic.AirQuality,
-        mapCo2ToAirQuality(co2, this.Characteristic.AirQuality, this.getAirQualityThresholds())
-      );
+      if (this.co2Service) {
+        this.co2Service.updateCharacteristic(this.Characteristic.CarbonDioxideLevel, co2);
+        this.co2Service.updateCharacteristic(
+          this.Characteristic.CarbonDioxideDetected,
+          co2 > co2Threshold
+            ? this.Characteristic.CarbonDioxideDetected.CO2_LEVELS_ABNORMAL
+            : this.Characteristic.CarbonDioxideDetected.CO2_LEVELS_NORMAL
+        );
+      }
+      if (this.airQualityService) {
+        this.airQualityService.updateCharacteristic(
+          this.Characteristic.AirQuality,
+          mapCo2ToAirQuality(co2, this.Characteristic.AirQuality, this.getAirQualityThresholds())
+        );
+      }
     }
 
     if (temperature !== null && temperature !== undefined) {
       this.lastReading.temperature = temperature;
       this.hasEverSucceeded = true;
-      this.temperatureService.updateCharacteristic(this.Characteristic.CurrentTemperature, temperature);
+      if (this.temperatureService) {
+        this.temperatureService.updateCharacteristic(this.Characteristic.CurrentTemperature, temperature);
+      }
+    }
+
+    if (hasReading) {
+      this.publishMqttReading();
     }
   }
 
   setFault(hasFault) {
+    if (!this.co2Service) return;
+
     const value = hasFault
       ? this.Characteristic.StatusFault.GENERAL_FAULT
       : this.Characteristic.StatusFault.NO_FAULT;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "homebridge-withings-environment-data",
-  "version": "1.2.0",
+  "displayName": "Withings Environment Data",
+  "version": "1.3.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": [
@@ -23,6 +24,9 @@
   ],
   "author": "Luud Jacobs",
   "license": "MIT",
+  "dependencies": {
+    "mqtt": "^5.15.0"
+  },
   "homepage": "https://github.com/LuudJacobs/homebridge-withings-environment-data#readme",
   "bugs": {
     "url": "https://github.com/LuudJacobs/homebridge-withings-environment-data/issues"