homebridge-withings-environment-data 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ 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

package/README.md

@@ -1,4 +1,4 @@
-# Homebridge Withings Environment Data v1.2.1
+# 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,16 +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 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 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);
@@ -198,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) {
@@ -441,27 +482,39 @@ class WithingsEnvironmentDataPlatform {
     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.1",
+  "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"