homebridge-ecobee-security 0.2.0 → 0.4.0

package/lib/airquality.js

@@ -0,0 +1,186 @@
+// Air quality from ecobee thermostats with the sensor (ecobee Premium): one accessory per thermostat
+// with an Air Quality Sensor (overall level, VOC) and a Carbon Dioxide Sensor (ppm, high-CO2 alert).
+// ecobee's own HomeKit integration doesn't expose these readings.
+import { SignInRequiredError } from './ecobee.js';
+
+const POLL = 5 * 60 * 1000;        // ecobee updates thermostat runtime every few minutes
+const FAULT_AFTER = 3;
+
+export class AirQualitySensors {
+  /**
+   * @param {object} options
+   * @param {import('homebridge').API} options.api
+   * @param {import('homebridge').Logging} options.log
+   * @param {import('./ecobee.js').EcobeeCloud} options.cloud
+   * @param {string} options.homeId
+   * @param {import('homebridge').PlatformAccessory[]} options.cached accessories restored by Homebridge
+   * @param {(uuid: string, name: string) => import('homebridge').PlatformAccessory} options.create new, unregistered accessory
+   * @param {(accessories: import('homebridge').PlatformAccessory[]) => void} options.register
+   * @param {(accessories: import('homebridge').PlatformAccessory[]) => void} options.update
+   * @param {(accessories: import('homebridge').PlatformAccessory[]) => void} options.unregister
+   * @param {number} options.co2Alert ppm at or above which the CO2 sensor reports abnormal levels
+   * @param {string} options.version plugin version, shown as firmware
+   */
+  constructor({ api, log, cloud, homeId, cached, create, register, update, unregister, co2Alert, version }) {
+    Object.assign(this, { api, log, cloud, homeId, cached, create, register, update, unregister, co2Alert, version });
+    this.C = api.hap.Characteristic;
+    this.sensors = new Map();      // thermostat id -> { accessory, air, co2 }
+    this.failures = 0;
+    this.stopped = false;
+  }
+
+  uuid(thermostatId) {
+    return this.api.hap.uuid.generate(`ecobee-security:air-quality:${thermostatId}`);
+  }
+
+  /** First read: create, keep or remove accessories to match the thermostats with air quality. */
+  async start() {
+    const thermostats = (await this.cloud.getAirQuality(this.homeId))
+      .filter(t => t.airQuality?.hasAirQualityEnabled);
+    const wanted = new Set(thermostats.map(t => this.uuid(t.id)));
+    const stale = this.cached.filter(a => !wanted.has(a.UUID));
+    if (stale.length) {
+      this.unregister(stale);
+    }
+    // Build each accessory completely (services and first readings) before it's published.
+    const added = [];
+    const kept = [];
+    for (const t of thermostats) {
+      const uuid = this.uuid(t.id);
+      const cached = this.cached.find(a => a.UUID === uuid);
+      const accessory = cached ?? this.create(uuid, `${t.name} Air Quality`);
+      (cached ? kept : added).push(accessory);
+      this.sensors.set(t.id, this.setUp(accessory, t));
+    }
+    this.apply(thermostats);
+    if (added.length) {
+      this.register(added);
+    }
+    if (kept.length) {
+      this.update(kept);
+    }
+    for (const t of thermostats) {
+      this.log.info(`Air quality, ${t.name}: ${describe(t)}.`);
+    }
+    this.schedule(POLL);
+  }
+
+  stop() {
+    this.stopped = true;
+    clearTimeout(this.timer);
+  }
+
+  schedule(delay) {
+    if (!this.stopped && this.sensors.size) {
+      clearTimeout(this.timer);
+      this.timer = setTimeout(() => this.poll(), delay);
+    }
+  }
+
+  setUp(accessory, thermostat) {
+    const { Service } = this.api.hap;
+    const C = this.C;
+    accessory.getService(Service.AccessoryInformation)
+      .setCharacteristic(C.Manufacturer, 'ecobee')
+      .setCharacteristic(C.Model, 'Thermostat air quality')
+      .setCharacteristic(C.SerialNumber, thermostat.id)
+      .setCharacteristic(C.FirmwareRevision, this.version);
+    const air = accessory.getService(Service.AirQualitySensor)
+      ?? accessory.addService(Service.AirQualitySensor, `${thermostat.name} Air Quality`);
+    // ecobee reports VOC in ppb, often above HomeKit's default 1000 limit.
+    air.getCharacteristic(C.VOCDensity).setProps({ maxValue: 10000 });
+    const co2 = accessory.getService(Service.CarbonDioxideSensor)
+      ?? accessory.addService(Service.CarbonDioxideSensor, `${thermostat.name} CO2`);
+    co2.getCharacteristic(C.CarbonDioxideLevel);
+    for (const service of [air, co2]) {
+      if (!service.testCharacteristic(C.StatusFault)) {
+        service.addCharacteristic(C.StatusFault);
+      }
+    }
+    return { accessory, air, co2, name: thermostat.name };
+  }
+
+  async poll() {
+    try {
+      this.apply(await this.cloud.getAirQuality(this.homeId));
+      if (this.failures >= FAULT_AFTER) {
+        this.log.info('Air quality readings are back.');
+      }
+      this.failures = 0;
+      this.setFault(false);
+    } catch (error) {
+      this.failures += 1;
+      if (this.failures === FAULT_AFTER) {
+        this.setFault(true);
+      }
+      if (!(error instanceof SignInRequiredError)) {
+        this.log[this.failures >= FAULT_AFTER ? 'warn' : 'debug'](`Could not read air quality (${error.message}).`);
+      }
+    }
+    this.schedule(POLL);
+  }
+
+  setFault(on) {
+    const { StatusFault } = this.C;
+    for (const { air, co2 } of this.sensors.values()) {
+      air.updateCharacteristic(StatusFault, on ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+      co2.updateCharacteristic(StatusFault, on ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+    }
+  }
+
+  apply(thermostats) {
+    const { AirQuality, VOCDensity, CarbonDioxideLevel, CarbonDioxideDetected } = this.C;
+    for (const t of thermostats) {
+      const sensor = this.sensors.get(t.id);
+      if (!sensor) {
+        continue;
+      }
+      const aq = t.airQuality ?? {};
+      const runtime = t.runtime ?? {};
+      sensor.air.updateCharacteristic(AirQuality, aq.isCalibrating ? AirQuality.UNKNOWN : level(aq.airQualityScore, AirQuality));
+      if (Number.isFinite(runtime.actualVOC) && runtime.actualVOC >= 0) {
+        sensor.air.updateCharacteristic(VOCDensity, Math.min(runtime.actualVOC, 10000));
+      }
+      if (Number.isFinite(runtime.actualCO2) && runtime.actualCO2 >= 0) {
+        sensor.co2.updateCharacteristic(CarbonDioxideLevel, Math.min(runtime.actualCO2, 100000));
+        sensor.co2.updateCharacteristic(CarbonDioxideDetected, runtime.actualCO2 >= this.co2Alert
+          ? CarbonDioxideDetected.CO2_LEVELS_ABNORMAL : CarbonDioxideDetected.CO2_LEVELS_NORMAL);
+      }
+      this.log.debug(`Air quality, ${sensor.name}: ${describe(t)}.`);
+    }
+  }
+}
+
+const LEVEL_NAMES = ['unknown', 'excellent', 'good', 'fair', 'inferior', 'poor'];
+
+function describe(t) {
+  const aq = t.airQuality ?? {};
+  const r = t.runtime ?? {};
+  const name = aq.isCalibrating ? 'calibrating' : LEVEL_NAMES[level(aq.airQualityScore, { UNKNOWN: 0, EXCELLENT: 1, GOOD: 2, FAIR: 3, INFERIOR: 4, POOR: 5 })];
+  return `${name} (score ${Number.isFinite(aq.airQualityScore) ? aq.airQualityScore.toFixed(2) : '?'}), `
+    + `CO2 ${r.actualCO2 ?? '?'} ppm, VOC ${r.actualVOC ?? '?'} ppb`;
+}
+
+/**
+ * ecobee's 0 (clean) … 1 (poor) score onto HomeKit's five levels, following the eight segments of
+ * the ecobee app's bar: 1–2 Excellent (the app calls 0.21 "Clean"), 3–4 Good, 5 Fair, 6 Inferior,
+ * 7–8 Poor.
+ */
+export function level(score, AirQuality) {
+  if (!Number.isFinite(score)) {
+    return AirQuality.UNKNOWN;
+  }
+  if (score < 0.25) {
+    return AirQuality.EXCELLENT;
+  }
+  if (score < 0.5) {
+    return AirQuality.GOOD;
+  }
+  if (score < 0.625) {
+    return AirQuality.FAIR;
+  }
+  if (score < 0.75) {
+    return AirQuality.INFERIOR;
+  }
+  return AirQuality.POOR;
+}

package/lib/auth.js

@@ -0,0 +1,121 @@
+// ecobee sign-in, shared by bin/ecobee-login.js and the Homebridge UI settings page.
+//
+// Password sign-in goes straight to Auth0's token endpoint as the ecobee app's client (no login
+// page, so no CAPTCHA), followed by the account's MFA code if it has MFA. The browser sign-in is
+// the fallback: the user signs in on ecobee's page and pastes the app callback URL.
+// Only the refresh token is kept; passwords and codes are passed through and never stored.
+import { createHash, randomBytes } from 'node:crypto';
+
+import { AUDIENCE, AUTH, CLIENT_ID, REDIRECT_URI, SCOPE } from './ecobee.js';
+
+const TIMEOUT = 20 * 1000;
+
+/** A sign-in step failed; `message` is ecobee's reason, fit to show the user. */
+export class SignInError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+}
+
+async function post(path, body) {
+  let res;
+  try {
+    res = await fetch(`${AUTH}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ client_id: CLIENT_ID, ...body }),
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+  } catch (error) {
+    throw new SignInError(`Could not reach ecobee (${error.message})`, 'network');
+  }
+  const json = await res.json().catch(() => ({}));
+  return { status: res.status, json };
+}
+
+function fail({ status, json }) {
+  const reason = json.error_description || json.error || `HTTP ${status}`;
+  return new SignInError(reason.endsWith('.') ? reason : `${reason}.`, json.error ?? `http_${status}`);
+}
+
+function tokens(json) {
+  if (!json.refresh_token) {
+    throw new SignInError('Signed in, but ecobee returned no refresh token.', 'no_refresh_token');
+  }
+  return json;
+}
+
+/**
+ * Step 1 of password sign-in. Resolves `{ tokens }` when no MFA is needed, otherwise
+ * `{ mfa }` to pass to finishMfa() together with the code ecobee asks for. `mfa.method` is
+ * 'otp' (authenticator app) or 'oob' (a code ecobee sends by SMS or email).
+ */
+export async function passwordSignIn(username, password) {
+  const first = await post('/oauth/token', { grant_type: 'password', username, password, audience: AUDIENCE, scope: SCOPE });
+  if (first.status === 200) {
+    return { tokens: tokens(first.json) };
+  }
+  if (first.json.error !== 'mfa_required') {
+    throw fail(first);
+  }
+  const mfaToken = first.json.mfa_token;
+  const challenge = await post('/mfa/challenge', { mfa_token: mfaToken, challenge_type: 'otp oob' });
+  if (challenge.status !== 200) {
+    throw fail(challenge);
+  }
+  return {
+    mfa: {
+      token: mfaToken,
+      method: challenge.json.challenge_type === 'oob' ? 'oob' : 'otp',
+      oobCode: challenge.json.oob_code,
+    },
+  };
+}
+
+/** Step 2 of password sign-in: the MFA code. */
+export async function finishMfa(mfa, code) {
+  const otp = String(code).replace(/\s+/g, '');
+  const result = mfa.method === 'oob'
+    ? await post('/oauth/token', { grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob', mfa_token: mfa.token, oob_code: mfa.oobCode, binding_code: otp })
+    : await post('/oauth/token', { grant_type: 'http://auth0.com/oauth/grant-type/mfa-otp', mfa_token: mfa.token, otp });
+  if (result.status !== 200) {
+    throw fail(result);
+  }
+  return tokens(result.json);
+}
+
+/** Browser sign-in, step 1: the link to open, plus what finishBrowserSignIn() needs later. */
+export function browserSignInLink() {
+  const verifier = randomBytes(32).toString('base64url');
+  const state = randomBytes(24).toString('base64url');
+  const url = new URL('/authorize', AUTH);
+  Object.entries({
+    audience: AUDIENCE, client_id: CLIENT_ID, redirect_uri: REDIRECT_URI, scope: SCOPE,
+    response_type: 'code', prompt: 'login', state, nonce: randomBytes(16).toString('hex'),
+    code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256',
+  }).forEach(([k, v]) => url.searchParams.set(k, v));
+  return { url: url.href, verifier, state };
+}
+
+/** Browser sign-in, step 2: the com.ecobee.athenamobile://…?code=… URL the user copied. */
+export async function finishBrowserSignIn(link, callbackUrl) {
+  let callback;
+  try {
+    callback = new URL(String(callbackUrl).trim());
+  } catch {
+    throw new SignInError('That isn\'t a URL. It should start with com.ecobee.athenamobile://', 'bad_url');
+  }
+  if (callback.searchParams.get('state') !== link.state) {
+    throw new SignInError('That URL is from a different sign-in attempt. Get a new link and try again.', 'bad_state');
+  }
+  const code = callback.searchParams.get('code');
+  if (!code) {
+    throw new SignInError('There\'s no code= in that URL.', 'bad_url');
+  }
+  const result = await post('/oauth/token', { grant_type: 'authorization_code', code, code_verifier: link.verifier, redirect_uri: REDIRECT_URI });
+  if (result.status !== 200) {
+    throw fail(result);
+  }
+  return tokens(result.json);
+}

package/lib/ecobee.js

@@ -2,6 +2,8 @@
 
 export const AUTH = 'https://auth.ecobee.com';
 export const GRAPHQL = 'https://federated-api.prod.federated-graph.generacapis.com/graphql';
+// ecobee's older REST API; the app still reads thermostat runtime (CO2 ppm, VOC) from it.
+export const REST = 'https://api.ecobee.com/1';
 export const CLIENT_ID = 'CuGkX8Ai7OWD2V1F32rFa7UJGRVRsnbv';
 export const REDIRECT_URI = 'com.ecobee.athenamobile://auth.ecobee.com/ios/com.ecobee.athenamobile/callback';
 export const AUDIENCE = 'https://prod.ecobee.com/api/v1';
@@ -24,6 +26,9 @@ const STATE_QUERY = `query HomesSecurity { homes { id name capabilities monitori
   + 'homeMonitoringSettings { isProfessionalMonitoringEnabled armedStateSettings { '
   + 'armedAway { entryDelayDuration exitDelayDuration } armedStay { entryDelayDuration exitDelayDuration } } } } } }';
 
+const AIR_QUALITY_QUERY = 'query ThermostatsAirQuality($homeID: ID!) { homes(id: $homeID) { id devices { id '
+  + 'thermostats { id name airQuality { hasAirQualityEnabled carbonDioxideScore vocScore airQualityScore isCalibrating } } } } }';
+
 const SET_MUTATION = 'mutation SetArmedStateForHome($input: SetArmedStateForHomeInput!) { '
   + `setArmedStateForHome(input: $input) { home { id monitoring { ${MONITORING_FIELDS} } } success } }`;
 
@@ -119,6 +124,41 @@ export class EcobeeCloud {
     return data.homes ?? [];
   }
 
+  /**
+   * The home's thermostats with ecobee's air quality scores (0 = clean … 1 = poor), plus the
+   * runtime readings (`actualCO2` ppm, `actualVOC` ppb, `actualAQScore`) from the REST API.
+   */
+  async getAirQuality(homeId) {
+    const data = await this.graphql('ThermostatsAirQuality', AIR_QUALITY_QUERY, { homeID: homeId });
+    const thermostats = data.homes?.[0]?.devices?.thermostats ?? [];
+    if (!thermostats.length) {
+      return [];
+    }
+    const json = await this.rest('/thermostat', {
+      selectionType: 'thermostats', selectionMatch: thermostats.map(t => t.id).join(','), includeRuntime: true,
+    });
+    const runtime = new Map((json.thermostatList ?? []).map(t => [t.identifier, t.runtime ?? {}]));
+    return thermostats.map(t => ({ ...t, runtime: runtime.get(t.id) ?? {} }));
+  }
+
+  async rest(path, selection, retry = true) {
+    const token = await this.token();
+    const url = `${REST}${path}?json=${encodeURIComponent(JSON.stringify({ selection }))}`;
+    const res = await fetch(url, {
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json;charset=UTF-8', 'user-agent': USER_AGENT },
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+    if (res.status === 401 && retry) {
+      this.accessToken = undefined;
+      return this.rest(path, selection, false);
+    }
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok || (json.status?.code ?? 0) !== 0) {
+      throw new Error(`${path}: HTTP ${res.status} ${json.status?.message ?? ''}`.trim());
+    }
+    return json;
+  }
+
   /**
    * @param {string} homeId
    * @param {string} armedState one of ArmedState

package/lib/platform.js

@@ -3,12 +3,17 @@ import { join } from 'node:path';
 
 import { EcobeeCloud, SignInRequiredError } from './ecobee.js';
 import { startControlServer } from './control.js';
+import { AirQualitySensors } from './airquality.js';
 import { SecuritySystem } from './security.js';
+import { VERSION } from './version.js';
 
 export const PLUGIN_NAME = 'homebridge-ecobee-security';
 export const PLATFORM_NAME = 'EcobeeSecurityPlatform';
 
 const RETRY_START = 60 * 1000;
+const AIR_QUALITY_RETRY = 10 * 60 * 1000;
+const AIR_QUALITY = 'airQuality';
+const SMOKE = 'smoke';
 
 export class EcobeeSecurityPlatform {
   /**
@@ -56,8 +61,10 @@ export class EcobeeSecurityPlatform {
     });
     api.on('shutdown', () => {
       clearTimeout(this.retryTimer);
+      clearTimeout(this.airQualityRetry);
       this.control?.close();
       this.system?.stop();
+      this.airQuality?.stop();
     });
   }
 
@@ -115,7 +122,9 @@ export class EcobeeSecurityPlatform {
     }
 
     const uuid = this.api.hap.uuid.generate(`ecobee-security:${home.id}`);
-    const stale = this.cached.filter(a => a.UUID !== uuid);
+    const smokeUuid = this.api.hap.uuid.generate(`ecobee-security:smoke:${home.id}`);
+    const wantSmoke = this.config.smokeSensor !== false;
+    const stale = this.cached.filter(a => a.UUID !== uuid && a.context.kind !== AIR_QUALITY && !(wantSmoke && a.UUID === smokeUuid));
     if (stale.length) {
       this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, stale);
     }
@@ -124,6 +133,12 @@ export class EcobeeSecurityPlatform {
     if (isNew) {
       accessory = new this.api.platformAccessory(this.config.name || 'Security System', uuid);
     }
+    let smokeAccessory = wantSmoke ? this.cached.find(a => a.UUID === smokeUuid) : undefined;
+    const smokeIsNew = wantSmoke && !smokeAccessory;
+    if (smokeIsNew) {
+      smokeAccessory = new this.api.platformAccessory('Smoke Alarm', smokeUuid);
+      smokeAccessory.context.kind = SMOKE;
+    }
 
     this.system = new SecuritySystem({
       api: this.api,
@@ -134,12 +149,20 @@ export class EcobeeSecurityPlatform {
       pollInterval: Math.max(5, Number(this.config.pollInterval) || 10),
       store: this.store,
       save: () => this.save(),
+      offerNight: this.config.offerNight === true,
+      alarmAfterEntryDelay: this.config.alarmTrigger === 'entryDelay',
+      smokeAccessory,
     });
     if (isNew) {
       this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
     } else {
       this.api.updatePlatformAccessories([accessory]);
     }
+    if (smokeIsNew) {
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [smokeAccessory]);
+    } else if (smokeAccessory) {
+      this.api.updatePlatformAccessories([smokeAccessory]);
+    }
     this.system.start();
     const m = home.monitoring;
     this.log.info(`Connected to "${home.name}" (${m.armedState}; professional monitoring `
@@ -147,5 +170,42 @@ export class EcobeeSecurityPlatform {
     if (this.store.hold) {
       this.log.info(`Still holding Stay for ${this.store.hold.by} (since ${this.store.hold.since}).`);
     }
+    this.startAirQuality(home.id);
+  }
+
+  /** Air quality sensors for thermostats that have them; failures here never affect the security system. */
+  async startAirQuality(homeId) {
+    const cached = this.cached.filter(a => a.context.kind === AIR_QUALITY);
+    if (this.config.airQuality === false) {
+      if (cached.length) {
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, cached);
+      }
+      return;
+    }
+    const sensors = new AirQualitySensors({
+      api: this.api,
+      log: this.log,
+      cloud: this.cloud,
+      homeId,
+      cached,
+      co2Alert: Math.max(400, Number(this.config.co2Alert) || 1000),
+      version: VERSION,
+      create: (uuid, name) => {
+        const accessory = new this.api.platformAccessory(name, uuid);
+        accessory.context.kind = AIR_QUALITY;
+        return accessory;
+      },
+      register: accessories => this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, accessories),
+      update: accessories => this.api.updatePlatformAccessories(accessories),
+      unregister: accessories => this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, accessories),
+    });
+    try {
+      await sensors.start();
+      this.airQuality = sensors;
+    } catch (error) {
+      sensors.stop();
+      this.log.warn(`Could not set up air quality (${error.message}); trying again in 10 minutes.`);
+      this.airQualityRetry = setTimeout(() => this.startAirQuality(homeId), AIR_QUALITY_RETRY);
+    }
   }
 }