homebridge-withings-environment-data 0.1.3

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh auth *)",
+      "Bash(gh repo *)"
+    ]
+  }
+}

package/.nova/Configuration.json

@@ -0,0 +1,3 @@
+{
+  "workspace.name" : "Withings Enironment Data"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luuuud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# Homebridge Withings Environment Data
+
+**This Homebridge plugin has been 100% vibe coded with Claude.**
+
+Exposes ambient CO2 (air quality) and room temperature readings from a
+Withings WS-50 scale as HomeKit sensors:
+
+- **CarbonDioxideSensor**: precise CO2 level in ppm, plus a normal/abnormal
+  detected alert based on a configurable threshold.
+- **AirQualitySensor**: the same CO2 reading mapped to HomeKit's
+  Excellent/Good/Fair/Inferior/Poor category.
+- **TemperatureSensor**: room temperature in °C.
+
+This data isn't available through the official Withings API: a `getmeas`
+call against the documented endpoint drops CO2/temperature even when
+explicitly requested. Instead this plugin authenticates the same way the
+Health Mate web app does (session cookies, not OAuth) and calls the same
+internal endpoint the web app uses. That means it depends on undocumented
+behavior of `account.withings.com` / `scalews.withings.com` and could break
+if Withings changes them.
+
+## Installation
+
+Install via the Homebridge Config UI: open the **Plugins** tab, search for
+"Withings Environment Data", and click **Install**.
+
+Or from the command line:
+
+```bash
+npm install -g homebridge-withings-environment-data
+```
+
+Then restart Homebridge and add the platform via the Config UI, or add it
+manually to `config.json`.
+
+## Configuration
+
+All settings are entered through the Homebridge Config UI (Plugins tab,
+Withings Environment Data, Settings).
+
+> **Note:** Homebridge stores your password and trust cookie value in plain
+> text in its `config.json` file on disk. Anyone with access to that file,
+> or to the Homebridge host itself, can read them. Treat that file with the
+> same care as any other credentials store.
+
+Fields:
+
+- **Withings Email / Password**: your account credentials. Used only
+  against `account.withings.com`'s own login form.
+- **Trust Cookie Name / Value**: see [Getting the trust
+  cookie](#getting-the-trust-cookie) below. As long as this is reused, the
+  plugin's automated logins skip the 2FA prompt.
+- **Poll Interval (minutes)**: how often to fetch new readings (default 30,
+  matching the scale's own upload cadence).
+- **CO2 Detected Threshold (ppm)**: ppm above which the CarbonDioxideSensor
+  reports "abnormal" (default 1000).
+
+## When it stops working
+
+If the Homebridge log shows a "session not trusted (landed on confirm_totp)"
+error, the device-trust cookie has been invalidated (e.g. after a password
+change, or Withings revoking trusted devices). The Home app will keep
+showing the last known good reading, it won't go blank, but a fault
+indicator appears on the sensors until this is fixed. Fix:
+
+1. Recapture the trust cookie: see [Getting the trust
+   cookie](#getting-the-trust-cookie) below.
+2. Update the **Trust Cookie Value** field in the plugin's Config UI
+   settings (the **Trust Cookie Name** itself should stay the same).
+
+Any other poll failure (network error, unexpected response) is logged the
+same way: an error in the Homebridge log, a fault indicator on the sensors,
+and the previous readings left in place until the next successful poll.
+
+## Getting the trust cookie
+
+Both initial setup and recovering from an expired session need this. Capture
+it once via DevTools:
+
+1. Log into [account.withings.com](https://account.withings.com) in a
+   browser, making sure to check **"trust this device"** when prompted for
+   a 2FA code.
+2. Open DevTools, Application tab, Cookies, `account.withings.com`.
+3. Find the cookie named `2fa_token_<a long hex hash>`, then copy its full
+   name and its value. This is what actually signals "this device already
+   passed 2FA". Its name stays stable across logins even though its value
+   doesn't.

package/config.schema.json

@@ -0,0 +1,54 @@
+{
+  "pluginAlias": "WithingsEnvironmentData",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Exposes ambient CO2/air-quality and room temperature from a Withings WS-50 scale as HomeKit sensors. This data isn't available through the official Withings API, so this plugin authenticates the same way the Health Mate web app does. See the README for how to capture the config values below via browser DevTools.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Withings Environment",
+        "required": true
+      },
+      "email": {
+        "title": "Withings Email",
+        "type": "string",
+        "required": true
+      },
+      "password": {
+        "title": "Withings Password",
+        "type": "string",
+        "required": true,
+        "x-schema-form": {
+          "type": "password"
+        }
+      },
+      "trustCookieName": {
+        "title": "Trust Cookie Name",
+        "type": "string",
+        "required": true,
+        "description": "The cookie named 2fa_token_<long hex hash> under account.withings.com — copy its full name here"
+      },
+      "trustCookieValue": {
+        "title": "Trust Cookie Value",
+        "type": "string",
+        "required": true,
+        "description": "The value of that same 2fa_token_<hash> cookie"
+      },
+      "pollIntervalMinutes": {
+        "title": "Poll Interval (minutes)",
+        "type": "integer",
+        "default": 30,
+        "minimum": 5
+      },
+      "co2DetectedThresholdPpm": {
+        "title": "CO2 Detected Threshold (ppm)",
+        "type": "integer",
+        "default": 1000,
+        "minimum": 400
+      }
+    }
+  }
+}

package/index.js

@@ -0,0 +1,208 @@
+const { login } = require('./lib/login');
+const { discoverDevice } = require('./lib/discover');
+
+const MEASURE_URL = 'https://scalews.withings.com/cgi-bin/v2/measure';
+// Reverse-engineered/unofficial: not part of the documented Withings API.
+const MEASTYPE_CO2 = 35;
+const MEASTYPE_TEMPERATURE = 12;
+const APPNAME = 'hmw';
+const APPPFM = 'web';
+// Wide enough to reliably find at least one recent point even after a longer
+// gap in scale uploads — only the single newest point per series is used.
+const WINDOW_HOURS = 48;
+
+const PLATFORM_NAME = 'WithingsEnvironmentData';
+
+async function fetchLatest({ cookieHeader, sessionToken, deviceId, userId }) {
+  const enddate = Math.floor(Date.now() / 1000);
+  const startdate = enddate - WINDOW_HOURS * 3600;
+
+  const body = new URLSearchParams({
+    action: 'getmeashf',
+    deviceid: deviceId,
+    userid: userId,
+    meastype: `${MEASTYPE_CO2},${MEASTYPE_TEMPERATURE}`,
+    startdate: String(startdate),
+    enddate: String(enddate),
+    appname: APPNAME,
+    apppfm: APPPFM,
+    session_token: sessionToken,
+  }).toString();
+
+  const response = await fetch(MEASURE_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'text/plain;charset=UTF-8',
+      Origin: 'https://app.withings.com',
+      Referer: 'https://app.withings.com/',
+      Cookie: cookieHeader,
+    },
+    body,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Measure request failed with HTTP status ${response.status}`);
+  }
+
+  const json = await response.json();
+  if (json.status !== 0) {
+    throw new Error(`Measure request returned Withings status ${json.status}: ${JSON.stringify(json.error ?? json)}`);
+  }
+
+  const co2Series = json.body.series?.find((s) => s.type === MEASTYPE_CO2)?.data ?? [];
+  const tempSeries = json.body.series?.find((s) => s.type === MEASTYPE_TEMPERATURE)?.data ?? [];
+
+  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,
+  };
+}
+
+function mapCo2ToAirQuality(ppm, AirQuality) {
+  if (ppm < 800) return AirQuality.EXCELLENT;
+  if (ppm < 1000) return AirQuality.GOOD;
+  if (ppm < 1500) return AirQuality.FAIR;
+  if (ppm < 2000) return AirQuality.INFERIOR;
+  return AirQuality.POOR;
+}
+
+class WithingsEnvironmentDataPlatform {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config;
+    this.api = api;
+    this.Service = api.hap.Service;
+    this.Characteristic = api.hap.Characteristic;
+    this.accessories = [];
+    // Discovered automatically from the Withings association endpoint on first
+    // successful login, rather than requiring the user to hunt for these in
+    // DevTools — see lib/discover.js.
+    this.deviceId = null;
+    this.userId = null;
+
+    this.api.on('didFinishLaunching', () => this.discoverDevices());
+  }
+
+  configureAccessory(accessory) {
+    this.log.info('Loading accessory from cache:', accessory.displayName);
+    this.accessories.push(accessory);
+  }
+
+  discoverDevices() {
+    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]);
+    }
+
+    this.setupServices(accessory);
+    this.startPolling();
+  }
+
+  setupServices(accessory) {
+    this.infoService = accessory.getService(this.Service.AccessoryInformation);
+    if (this.infoService) {
+      this.infoService
+        .setCharacteristic(this.Characteristic.Manufacturer, 'Withings')
+        .setCharacteristic(this.Characteristic.Model, 'WS-50')
+        .setCharacteristic(this.Characteristic.SerialNumber, 'pending discovery');
+    }
+
+    this.co2Service =
+      accessory.getService(this.Service.CarbonDioxideSensor) ||
+      accessory.addService(this.Service.CarbonDioxideSensor, 'CO2', 'co2');
+
+    this.airQualityService =
+      accessory.getService(this.Service.AirQualitySensor) ||
+      accessory.addService(this.Service.AirQualitySensor, 'Air Quality', 'air-quality');
+
+    this.temperatureService =
+      accessory.getService(this.Service.TemperatureSensor) ||
+      accessory.addService(this.Service.TemperatureSensor, 'Temperature', 'temperature');
+  }
+
+  startPolling() {
+    const minutes = Number(this.config.pollIntervalMinutes);
+    const intervalMs = (Number.isFinite(minutes) && minutes > 0 ? minutes : 30) * 60 * 1000;
+
+    this.poll();
+    this.pollTimer = setInterval(() => this.poll(), intervalMs);
+  }
+
+  async poll() {
+    try {
+      const { cookieHeader, sessionToken } = await login(
+        this.config.email,
+        this.config.password,
+        this.config.trustCookieName,
+        this.config.trustCookieValue
+      );
+
+      if (!this.deviceId || !this.userId) {
+        const discovered = await discoverDevice(cookieHeader);
+        this.deviceId = discovered.deviceId;
+        this.userId = discovered.userId;
+        this.log.info(`Discovered Withings device ${this.deviceId} for user ${this.userId}`);
+        if (this.infoService) {
+          this.infoService.setCharacteristic(this.Characteristic.SerialNumber, this.deviceId);
+        }
+      }
+
+      const { co2, temperature } = await fetchLatest({
+        cookieHeader,
+        sessionToken,
+        deviceId: this.deviceId,
+        userId: this.userId,
+      });
+
+      this.applyReading(co2, temperature);
+      this.setFault(false);
+    } catch (err) {
+      // Deliberately do not touch the value characteristics here — the Home app
+      // should keep showing the last known good reading, not go blank, when a
+      // poll fails (e.g. the trust cookie expired and login needs recapturing).
+      this.log.error(`Withings poll failed: ${err.message}`);
+      this.setFault(true);
+    }
+  }
+
+  applyReading(co2, temperature) {
+    const threshold = Number(this.config.co2DetectedThresholdPpm);
+    const co2Threshold = Number.isFinite(threshold) && threshold > 0 ? threshold : 1000;
+
+    if (co2 !== null && co2 !== undefined) {
+      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)
+      );
+    }
+
+    if (temperature !== null && temperature !== undefined) {
+      this.temperatureService.updateCharacteristic(this.Characteristic.CurrentTemperature, temperature);
+    }
+  }
+
+  setFault(hasFault) {
+    const value = hasFault
+      ? this.Characteristic.StatusFault.GENERAL_FAULT
+      : this.Characteristic.StatusFault.NO_FAULT;
+
+    this.co2Service.updateCharacteristic(this.Characteristic.StatusFault, value);
+    this.airQualityService.updateCharacteristic(this.Characteristic.StatusFault, value);
+    this.temperatureService.updateCharacteristic(this.Characteristic.StatusFault, value);
+  }
+}
+
+module.exports = (api) => {
+  api.registerPlatform(PLATFORM_NAME, WithingsEnvironmentDataPlatform);
+};

package/lib/discover.js

@@ -0,0 +1,39 @@
+const ASSOCIATION_URL = 'https://scalews.withings.com/cgi-bin/association';
+
+// Reverse-engineered/unofficial: not part of the documented Withings API.
+// Lets the plugin find the account's scale deviceId/userId automatically
+// after login, instead of requiring the user to hunt for them in DevTools.
+async function discoverDevice(cookieHeader) {
+  const body = new URLSearchParams({ action: 'getbyaccountid', enrich: 't' }).toString();
+
+  const response = await fetch(ASSOCIATION_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'text/plain;charset=UTF-8',
+      Origin: 'https://app.withings.com',
+      Referer: 'https://app.withings.com/',
+      Cookie: cookieHeader,
+    },
+    body,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Device discovery request failed with HTTP status ${response.status}`);
+  }
+
+  const json = await response.json();
+  if (json.status !== 0) {
+    throw new Error(`Device discovery returned Withings status ${json.status}`);
+  }
+
+  const deviceId = json.body.associations?.[0]?.deviceid;
+  const userId = json.body.accounts?.[0]?.users?.[0]?.userid;
+
+  if (!deviceId || !userId) {
+    throw new Error('Could not determine deviceId/userId from the Withings association response');
+  }
+
+  return { deviceId: String(deviceId), userId: String(userId) };
+}
+
+module.exports = { discoverDevice };

package/lib/login.js

@@ -0,0 +1,142 @@
+const ACCOUNT_BASE = 'https://account.withings.com';
+const USER_AGENT =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36';
+
+class CookieJar {
+  constructor() {
+    this.cookies = new Map();
+  }
+
+  setFromResponse(response) {
+    const setCookieHeaders =
+      typeof response.headers.getSetCookie === 'function'
+        ? response.headers.getSetCookie()
+        : response.headers.get('set-cookie')
+          ? [response.headers.get('set-cookie')]
+          : [];
+    for (const header of setCookieHeaders) {
+      const pair = header.split(';', 1)[0];
+      const eqIdx = pair.indexOf('=');
+      if (eqIdx === -1) continue;
+      const name = pair.slice(0, eqIdx).trim();
+      const value = pair.slice(eqIdx + 1).trim();
+      // Withings clears cookies by setting value to the literal string "deleted"
+      // (alongside an expired Expires attribute) rather than omitting them.
+      if (value === 'deleted' || /expires=[^;]*1970/i.test(header)) {
+        this.cookies.delete(name);
+      } else {
+        this.cookies.set(name, value);
+      }
+    }
+  }
+
+  set(name, value) {
+    this.cookies.set(name, value);
+  }
+
+  toHeader() {
+    return Array.from(this.cookies.entries())
+      .map(([name, value]) => `${name}=${value}`)
+      .join('; ');
+  }
+
+  findByPrefix(prefix) {
+    for (const [name, value] of this.cookies) {
+      if (name.startsWith(prefix)) return { name, value };
+    }
+    return null;
+  }
+}
+
+async function requestFollowingRedirects(method, url, body, jar, maxHops = 10) {
+  let currentUrl = url;
+  let currentMethod = method;
+  let currentBody = body;
+
+  for (let hop = 0; hop <= maxHops; hop++) {
+    const headers = {
+      Cookie: jar.toHeader(),
+      'User-Agent': USER_AGENT,
+      Origin: ACCOUNT_BASE,
+      Referer: currentUrl,
+    };
+    if (currentBody) headers['Content-Type'] = 'application/x-www-form-urlencoded';
+
+    const response = await fetch(currentUrl, {
+      method: currentMethod,
+      headers,
+      body: currentBody,
+      redirect: 'manual',
+    });
+    jar.setFromResponse(response);
+
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get('location');
+      if (!location) return { response, finalUrl: currentUrl };
+      currentUrl = new URL(location, currentUrl).toString();
+      currentMethod = 'GET';
+      currentBody = undefined;
+      continue;
+    }
+
+    if (response.status >= 400) {
+      throw new Error(
+        `Withings login request to ${currentUrl} failed with status ${response.status}`
+      );
+    }
+
+    return { response, finalUrl: currentUrl };
+  }
+
+  throw new Error(`Withings login exceeded ${maxHops} redirect hops starting from ${url}`);
+}
+
+async function login(email, password, trustCookieName, trustCookieValue) {
+  const jar = new CookieJar();
+  // This cookie (scoped to account.withings.com) is the "this device already passed
+  // 2FA" marker — its name has stayed stable across many logins. It must be sent on
+  // the very first request of a fresh login attempt, before email/password. Confirmed
+  // empirically that no other cookie (e.g. w_uuid) is needed alongside it.
+  jar.set(trustCookieName, trustCookieValue);
+
+  await requestFollowingRedirects('GET', `${ACCOUNT_BASE}/`, undefined, jar);
+
+  const emailBody = new URLSearchParams({ email }).toString();
+  await requestFollowingRedirects(
+    'POST',
+    `${ACCOUNT_BASE}/new_workflow/login`,
+    emailBody,
+    jar
+  );
+
+  const passwordBody = new URLSearchParams({ password }).toString();
+  const { finalUrl } = await requestFollowingRedirects(
+    'POST',
+    `${ACCOUNT_BASE}/new_workflow/password_check`,
+    passwordBody,
+    jar
+  );
+
+  if (finalUrl.includes('confirm_totp')) {
+    throw new Error(
+      "Withings session not trusted (landed on confirm_totp) — log in manually at " +
+        "https://account.withings.com with 'trust this device' checked during the 2FA step, " +
+        'then update the trustCookieValue plugin config field with a fresh value ' +
+        '(DevTools -> Application tab -> Cookies -> account.withings.com).'
+    );
+  }
+
+  const sessionTokenCookie = jar.findByPrefix('2fa_token_');
+  if (!sessionTokenCookie) {
+    throw new Error(
+      'Withings login completed but no 2fa_token_* cookie was found — the login flow may have changed.'
+    );
+  }
+
+  return {
+    cookieHeader: jar.toHeader(),
+    sessionToken: sessionTokenCookie.value,
+  };
+}
+
+module.exports = { login };

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "homebridge-withings-environment-data",
+  "version": "0.1.3",
+  "description": "Homebridge plugin exposing ambient CO2/air-quality and room temperature readings from a Withings WS-50 scale as HomeKit sensors",
+  "main": "index.js",
+  "keywords": [
+    "homebridge-plugin"
+  ],
+  "engines": {
+    "homebridge": ">=1.6.0",
+    "node": ">=18"
+  },
+  "license": "MIT"
+}