homebridge-ge-ac 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 the homebridge-ge-ac contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# homebridge-ge-ac
+
+A [Homebridge](https://homebridge.io) plugin for **GE Profile / SmartHQ Wi‑Fi window air conditioners**
+(e.g. the GE Profile ClearView **AHTT06BC**), exposing them to HomeKit with **reliable** setpoint,
+mode, and fan control.
+
+## Why this exists
+
+GE's SmartHQ appliances expose two interfaces:
+
+- a **REST** API that works fine for *reading* ERD values, and
+- a persistent authenticated **WebSocket** ("pseudo‑MQTT") channel that the GE app — and the
+  reference Python library [`simbaja/gehome`](https://github.com/simbaja/gehome) — use for
+  *control*.
+
+Existing Homebridge SmartHQ plugins write setpoints over **REST**. On at least the ClearView
+window-AC line, the backend *accepts* those REST writes (`200 OK`) but silently never relays them
+to the unit — so the temperature you set in HomeKit snaps right back. This plugin sends writes over
+the **WebSocket** channel (`setErd`), which the appliance actually honors. Confirmed end‑to‑end:
+the unit echoes the change back on `publish#erd`.
+
+## Features
+
+- Proper **HeaterCooler** thermostat — on/off, target temperature (64–86 °F), current temperature.
+  Setpoint changes **stick**.
+- **Mode switches** with real names: Cool, Fan Only, Energy Saver, Dry. (No bogus "Heat" — these
+  are cooling-only units. Each switch sets `ConfiguredName`, so HomeKit never shows "Switch 1–5".)
+- **Fan speed** via the rotation-speed slider (Auto / Low / Med / High).
+- **Live updates** — state is pushed from the WebSocket subscription, so HomeKit reflects changes
+  made in the GE app or on the unit, in real time.
+- Resilient: app‑level keepalive, OAuth token refresh ahead of expiry, and exponential‑backoff
+  auto‑reconnect.
+
+## Install
+
+```bash
+npm install -g homebridge-ge-ac     # or install a local checkout: npm install /path/to/homebridge-ge-ac
+```
+
+Then add the platform via the Homebridge UI (search "GE Profile AC") or in `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "GEProfileAC",
+      "name": "Air Conditioner",
+      "username": "you@example.com",
+      "password": "your-smarthq-password"
+    }
+  ]
+}
+```
+
+- `username` / `password` — the same credentials you use in the GE **SmartHQ** app. The AC must
+  already be set up and online in that app.
+- `macAddress` *(optional)* — only needed if more than one appliance is on the account; otherwise
+  the air conditioner is auto-detected.
+
+Running it as a **child bridge** (Homebridge UI → Bridge Settings) is recommended for isolation.
+
+## How it works
+
+| Concern | Approach |
+| --- | --- |
+| Auth | OAuth2 authorization-code flow scripted through the Brillion login form (`/oauth2/auth` → `g_authenticate` → `/oauth2/token`), then `GET /v1/websocket` for the signed socket endpoint + `userId`. |
+| Transport | One WebSocket: `subscribe` to `/appliance/*/erd/*`, list appliances, pull full ERD state, then receive live `publish#erd` updates. |
+| Writes | `setErd` over the socket — `{kind:"websocket#api", method:"POST", path:"/v1/appliance/{mac}/erd/{code}", body:{kind:"appliance#erdListEntry", …, value}}`, acked by echoed `id`. |
+| Encoding | Target temp ERD `0x7003` = 2‑byte big‑endian °F (`72 → "0048"`); mode `0x7A01`, power `0x7A0F`, ambient `0x7A02`, fan `0x7A00`. |
+
+See [`dev/`](dev/) for the standalone proof-of-concept (`poc-setpoint.js`) and module smoke test
+(`smoke.js`) used to validate the WebSocket write path before building the plugin.
+
+## Credits
+
+The GE SmartHQ / Brillion protocol details (OAuth flow, WebSocket envelopes, ERD codes and
+encodings) were derived from the excellent [`simbaja/gehome`](https://github.com/simbaja/gehome)
+Python library. This plugin is an independent JavaScript implementation.
+
+## License
+
+ISC — see [LICENSE](LICENSE).

package/config.schema.json

@@ -0,0 +1,34 @@
+{
+  "pluginAlias": "GEProfileAC",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Controls a GE Profile / SmartHQ Wi-Fi window air conditioner over GE's realtime WebSocket channel (reliable setpoint, mode, and fan control). Enter the same email + password you use in the GE SmartHQ app.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Accessory Name",
+        "type": "string",
+        "default": "Air Conditioner",
+        "description": "Name shown in HomeKit (you can also rename it in the Home app)."
+      },
+      "username": {
+        "title": "SmartHQ Email",
+        "type": "string",
+        "required": true,
+        "format": "email"
+      },
+      "password": {
+        "title": "SmartHQ Password",
+        "type": "string",
+        "required": true,
+        "x-schema-form": { "type": "password" }
+      },
+      "macAddress": {
+        "title": "Appliance ID / MAC (optional)",
+        "type": "string",
+        "description": "Only needed if more than one appliance is on the account. Leave blank to auto-detect the air conditioner."
+      }
+    }
+  }
+}

package/index.js

@@ -0,0 +1,7 @@
+'use strict';
+const { PLUGIN_NAME, PLATFORM_NAME } = require('./lib/const');
+const { GEACPlatform } = require('./lib/platform');
+
+module.exports = (api) => {
+  api.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, GEACPlatform);
+};

package/lib/accessory.js

@@ -0,0 +1,143 @@
+'use strict';
+const C = require('./const');
+
+// Build a HeaterCooler + 4 mode switches for one GE AC, bound to the SmartHQ client.
+class ACAccessory {
+  constructor(platform, accessory, client, mac) {
+    this.platform = platform;
+    this.log = platform.log;
+    this.accessory = accessory;
+    this.client = client;
+    this.mac = mac;
+    this.hap = platform.api.hap;
+    this.S = this.hap.Service;
+    this.Ch = this.hap.Characteristic;
+    const name = accessory.displayName;
+
+    accessory.getService(this.S.AccessoryInformation)
+      .setCharacteristic(this.Ch.Manufacturer, 'GE Appliances')
+      .setCharacteristic(this.Ch.Model, 'Smart Window AC')
+      .setCharacteristic(this.Ch.SerialNumber, mac);
+
+    // ---- HeaterCooler ----
+    const hc = accessory.getService(this.S.HeaterCooler) || accessory.addService(this.S.HeaterCooler, name, 'GEAC_HC');
+    this.hc = hc;
+    this._configuredName(hc, name);
+
+    hc.getCharacteristic(this.Ch.Active)
+      .onGet(() => this._power() ? this.Ch.Active.ACTIVE : this.Ch.Active.INACTIVE)
+      .onSet(this._wrap(async (v) => {
+        if (v === this.Ch.Active.ACTIVE) {
+          if (!this._power()) { await this.client.setErd(this.mac, C.ERD.POWER, C.POWER.ON); await this.client.setErd(this.mac, C.ERD.OPERATION_MODE, this._mode() || C.MODE.COOL); }
+        } else if (this._power()) { await this.client.setErd(this.mac, C.ERD.POWER, C.POWER.OFF); }
+      }));
+
+    hc.getCharacteristic(this.Ch.CurrentHeaterCoolerState)
+      .setProps({ validValues: [this.Ch.CurrentHeaterCoolerState.INACTIVE, this.Ch.CurrentHeaterCoolerState.IDLE, this.Ch.CurrentHeaterCoolerState.COOLING] })
+      .onGet(() => this._currentState());
+
+    hc.getCharacteristic(this.Ch.TargetHeaterCoolerState)
+      .setProps({ validValues: [this.Ch.TargetHeaterCoolerState.COOL] })
+      .onGet(() => this.Ch.TargetHeaterCoolerState.COOL)
+      .onSet(this._wrap(async () => {
+        if (!this._power()) await this.client.setErd(this.mac, C.ERD.POWER, C.POWER.ON);
+        await this.client.setErd(this.mac, C.ERD.OPERATION_MODE, C.MODE.COOL);
+      }));
+
+    hc.getCharacteristic(this.Ch.CurrentTemperature)
+      .onGet(() => C.fToC(this._ambientF()));
+
+    // Step = exactly 1 degF (5/9 degC), anchored at 64F, so the HomeKit grid lands on whole
+    // Fahrenheit degrees (64,65,...,86). minValue/maxValue are COMPUTED (not rounded literals)
+    // so the pushed value at a boundary equals the prop exactly and HAP never rejects it.
+    hc.getCharacteristic(this.Ch.CoolingThresholdTemperature)
+      .setProps({ minValue: C.fToC(64), maxValue: C.fToC(86), minStep: 5 / 9 })
+      .onGet(() => this._coolThreshC())
+      .onSet(this._wrap(async (v) => {
+        let f = Math.round(C.cToF(v));
+        f = Math.max(64, Math.min(86, f));
+        await this.client.setErd(this.mac, C.ERD.TARGET_TEMP, C.encodeTempF(f));
+      }));
+
+    hc.getCharacteristic(this.Ch.RotationSpeed)
+      .onGet(() => this._fanPct())
+      .onSet(this._wrap(async (pct) => { await this.client.setErd(this.mac, C.ERD.FAN, this._fanFromPct(pct)); }));
+
+    hc.getCharacteristic(this.Ch.TemperatureDisplayUnits)
+      .onGet(() => (this.client.getState(this.mac, C.ERD.TEMP_UNIT) === '01') ? this.Ch.TemperatureDisplayUnits.CELSIUS : this.Ch.TemperatureDisplayUnits.FAHRENHEIT);
+
+    // ---- mode switches (no HEAT; cooling-only unit) ----
+    this.switches = [
+      ['Cool', 'GEAC_COOL', C.MODE.COOL],
+      ['Fan Only', 'GEAC_FAN', C.MODE.FAN_ONLY],
+      ['Energy Saver', 'GEAC_ECO', C.MODE.ENERGY_SAVER],
+      ['Dry', 'GEAC_DRY', C.MODE.DRY],
+    ].map(([label, subtype, modeHex]) => {
+      const sw = accessory.getService(subtype) || accessory.addService(this.S.Switch, label, subtype);
+      this._configuredName(sw, label);
+      sw.getCharacteristic(this.Ch.On)
+        .onGet(() => this._power() && this._mode() === modeHex)
+        .onSet(this._wrap(async (on) => {
+          if (on) { if (!this._power()) await this.client.setErd(this.mac, C.ERD.POWER, C.POWER.ON); await this.client.setErd(this.mac, C.ERD.OPERATION_MODE, modeHex); }
+          else if (this._power() && this._mode() === modeHex) { await this.client.setErd(this.mac, C.ERD.POWER, C.POWER.OFF); }
+        }));
+      return { sw, modeHex };
+    });
+
+    // remove a stale HEAT switch if a previous version created one
+    const stale = accessory.getService('GEAC_HEAT');
+    if (stale) accessory.removeService(stale);
+
+    // live updates
+    this._onErd = (mac) => { if (mac === this.mac) this._pushAll(); };
+    client.on('erd', this._onErd);
+  }
+
+  _configuredName(svc, name) {
+    svc.setCharacteristic(this.Ch.Name, name);
+    if (!svc.testCharacteristic(this.Ch.ConfiguredName)) svc.addCharacteristic(this.Ch.ConfiguredName);
+    svc.getCharacteristic(this.Ch.ConfiguredName).onGet(() => name).updateValue(name);
+  }
+
+  _power() { return this.client.getState(this.mac, C.ERD.POWER) === C.POWER.ON; }
+  _mode() { return this.client.getState(this.mac, C.ERD.OPERATION_MODE); }
+  _targetF() { const v = C.decodeInt(this.client.getState(this.mac, C.ERD.TARGET_TEMP)); return (v != null && v >= 60 && v <= 90) ? v : 72; }
+  // cooling-threshold in Celsius, clamped to the characteristic's valid band so a boundary
+  // float (e.g. fToC(64)=17.7777 vs a 17.7778 min) can never be rejected by HAP
+  _coolThreshC() { return Math.max(C.fToC(64), Math.min(C.fToC(86), C.fToC(this._targetF()))); }
+  _ambientF() { const v = C.decodeInt(this.client.getState(this.mac, C.ERD.AMBIENT_TEMP)); return (v != null && v >= 32 && v <= 120) ? v : this._targetF(); }
+  _currentState() {
+    if (!this._power()) return this.Ch.CurrentHeaterCoolerState.INACTIVE;
+    return (this._ambientF() > this._targetF()) ? this.Ch.CurrentHeaterCoolerState.COOLING : this.Ch.CurrentHeaterCoolerState.IDLE;
+  }
+  _fanPct() {
+    const n = C.decodeInt(this.client.getState(this.mac, C.ERD.FAN));
+    if (n == null) return 0;
+    if (n >= 8) return 100; if (n >= 4) return 66; if (n >= 2) return 33; return 0; // 0/1 => AUTO
+  }
+  _fanFromPct(p) { if (p <= 0) return C.FAN.AUTO; if (p <= 33) return C.FAN.LOW; if (p <= 66) return C.FAN.MED; return C.FAN.HIGH; }
+
+  _pushAll() {
+    const u = (c, v) => { try { this.hc.updateCharacteristic(c, v); } catch (e) { /* ignore */ } };
+    u(this.Ch.Active, this._power() ? this.Ch.Active.ACTIVE : this.Ch.Active.INACTIVE);
+    u(this.Ch.CurrentHeaterCoolerState, this._currentState());
+    u(this.Ch.CurrentTemperature, C.fToC(this._ambientF()));
+    u(this.Ch.CoolingThresholdTemperature, this._coolThreshC());
+    u(this.Ch.RotationSpeed, this._fanPct());
+    for (const { sw, modeHex } of this.switches) {
+      try { sw.updateCharacteristic(this.Ch.On, this._power() && this._mode() === modeHex); } catch (e) { /* ignore */ }
+    }
+  }
+
+  _wrap(fn) {
+    return async (v) => {
+      try { await fn(v); }
+      catch (e) {
+        this.log.warn(`[${this.accessory.displayName}] set failed: ${e.message}`);
+        throw new this.hap.HapStatusError(this.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+      }
+    };
+  }
+}
+
+module.exports = { ACAccessory };

package/lib/auth.js

@@ -0,0 +1,111 @@
+'use strict';
+// GE SmartHQ OAuth2 authorization-code login (form scrape) + refresh.
+// Ported verbatim from the proven PoC / simbaja gehome async_login_flows.py.
+const axios = require('axios');
+const cheerio = require('cheerio');
+const C = require('./const');
+
+function makeJar() {
+  const jar = { abgea_region: C.REGION_COOKIE };
+  const header = () => Object.entries(jar).map(([k, v]) => `${k}=${v}`).join('; ');
+  const absorb = (res) => {
+    const sc = res.headers['set-cookie'];
+    if (!sc) return;
+    for (const line of sc) {
+      const pair = line.split(';')[0];
+      const i = pair.indexOf('=');
+      if (i > 0) jar[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
+    }
+  };
+  const req = async (cfg) => {
+    cfg.headers = Object.assign({ Cookie: header() }, cfg.headers || {});
+    cfg.maxRedirects = 0;
+    cfg.validateStatus = () => true;
+    cfg.timeout = 30000;
+    const res = await axios(cfg);
+    absorb(res);
+    return res;
+  };
+  return { req };
+}
+
+function formInputs(html, formId) {
+  const $ = cheerio.load(html);
+  const out = {};
+  $(`form#${formId}`).find('input').each((_, el) => {
+    const name = $(el).attr('name');
+    if (name) out[name] = $(el).attr('value') || '';
+  });
+  return out;
+}
+function codeFromLocation(loc) {
+  if (!loc) return null;
+  try { return new URL(loc, C.LOGIN_URL).searchParams.get('code'); } catch { return null; }
+}
+
+async function handleResponse(req, res, depth = 0) {
+  if (depth > 10) throw new Error('login: too many redirects');
+  if ([301, 302, 303, 307, 308].includes(res.status)) {
+    const loc = res.headers.location || '';
+    const code = codeFromLocation(loc);
+    if (code) return code;
+    const next = new URL(loc, C.LOGIN_URL).toString();
+    return handleResponse(req, await req({ method: 'GET', url: next }), depth + 1);
+  }
+  if (res.status === 200) {
+    const html = res.data;
+    if (/addMfaForm|Multi-Factor Authentication|\/account\/active\/security\/add\/mfamethod/.test(html)) {
+      const f = formInputs(html, 'addMfaForm');
+      if (!Object.keys(f).length) throw new Error('MFA enrollment required — configure/disable MFA in the SmartHQ app, then restart Homebridge');
+      return handleResponse(req, await req({ method: 'POST', url: `${C.LOGIN_URL}/account/active/redirect`, headers: { 'content-type': 'application/x-www-form-urlencoded' }, data: new URLSearchParams(f).toString() }), depth + 1);
+    }
+    if (/\/oauth2\/terms\/accept/.test(html)) {
+      const $ = cheerio.load(html); const f = {};
+      $('form input').each((_, el) => { const n = $(el).attr('name'); if (n) f[n] = $(el).attr('value') || ''; });
+      f.developerTerms = 'on'; f.connected_terms = 'on';
+      return handleResponse(req, await req({ method: 'POST', url: `${C.LOGIN_URL}/oauth2/terms/accept`, headers: { 'content-type': 'application/x-www-form-urlencoded' }, data: new URLSearchParams(f).toString() }), depth + 1);
+    }
+    const f = formInputs(html, 'frmsignin');
+    if ('authorized' in f) {
+      f.authorized = 'yes';
+      return handleResponse(req, await req({ method: 'POST', url: `${C.LOGIN_URL}/oauth2/code`, headers: { 'content-type': 'application/x-www-form-urlencoded' }, data: new URLSearchParams(f).toString() }), depth + 1);
+    }
+    const $ = cheerio.load(html);
+    const alert = $('#alert_pane').text().trim();
+    throw new Error(alert ? `auth failed: ${alert}` : 'auth failed: unexpected login page');
+  }
+  throw new Error(`login: unexpected status ${res.status}`);
+}
+
+async function login(username, password) {
+  const { req } = makeJar();
+  const params = new URLSearchParams({ client_id: C.CLIENT_ID, response_type: 'code', access_type: 'offline', redirect_uri: C.REDIRECT_URI });
+  const page = await req({ method: 'GET', url: `${C.LOGIN_URL}/oauth2/auth?${params}` });
+  if (page.status >= 400) throw new Error(`GET /oauth2/auth -> ${page.status}`);
+  const post = formInputs(page.data, 'frmsignin');
+  if (!Object.keys(post).length) throw new Error('login page had no #frmsignin form');
+  post.username = String(username).trim();
+  post.password = password;
+  const res = await req({ method: 'POST', url: `${C.LOGIN_URL}/oauth2/g_authenticate`, headers: { 'content-type': 'application/x-www-form-urlencoded', origin: C.LOGIN_URL }, data: new URLSearchParams(post).toString() });
+  if (res.status >= 400 && res.status < 500) throw new Error(`g_authenticate -> ${res.status} (check username/password)`);
+  const code = await handleResponse(req, res);
+  return exchange(req, new URLSearchParams({ code, client_id: C.CLIENT_ID, client_secret: C.CLIENT_SECRET, redirect_uri: C.REDIRECT_URI, grant_type: 'authorization_code' }));
+}
+
+async function refresh(refreshToken) {
+  const { req } = makeJar();
+  return exchange(req, new URLSearchParams({ refresh_token: refreshToken, client_id: C.CLIENT_ID, client_secret: C.CLIENT_SECRET, redirect_uri: C.REDIRECT_URI, grant_type: 'refresh_token' }));
+}
+
+async function exchange(req, body) {
+  const basic = Buffer.from(`${C.CLIENT_ID}:${C.CLIENT_SECRET}`).toString('base64');
+  const tok = await req({ method: 'POST', url: `${C.LOGIN_URL}/oauth2/token`, headers: { authorization: `Basic ${basic}`, 'content-type': 'application/x-www-form-urlencoded' }, data: body.toString() });
+  if (tok.status >= 400 || !tok.data || !tok.data.access_token) {
+    const err = new Error(`token endpoint -> ${tok.status}: ${JSON.stringify(tok.data).slice(0, 160)}`);
+    err.invalidGrant = tok.data && tok.data.error === 'invalid_grant';
+    throw err;
+  }
+  return tok.data; // { access_token, refresh_token, expires_in, ... }
+}
+
+module.exports = { login, refresh };

package/lib/client.js

@@ -0,0 +1,191 @@
+'use strict';
+const EventEmitter = require('events');
+const axios = require('axios');
+const WebSocket = require('ws');
+const C = require('./const');
+const auth = require('./auth');
+
+// SmartHQClient: owns auth + the realtime websocket. Emits:
+//   'appliances' (items[])           — appliance list received
+//   'erd' (mac, erdNorm, value)      — an ERD value updated (live)
+//   'status' (text)                  — connection status for logging
+class SmartHQClient extends EventEmitter {
+  constructor(log, username, password) {
+    super();
+    this.log = log;
+    this.username = username;
+    this.password = password;
+    this.token = null;
+    this.refreshToken = null;
+    this.userId = null;
+    this.endpoint = null;
+    this.ws = null;
+    this.state = new Map(); // mac -> { erdNorm: value }
+    this.pending = new Map(); // id -> {resolve, reject, timer}
+    this.reconnectDelay = C.RECONNECT_BASE_MS;
+    this.stopped = false;
+    this.connecting = false;
+    this._timers = { keepalive: null, relist: null, refresh: null, reconnect: null };
+  }
+
+  start() { this._connect(false); }
+
+  stop() {
+    this.stopped = true;
+    for (const k of Object.keys(this._timers)) if (this._timers[k]) clearTimeout(this._timers[k]) || clearInterval(this._timers[k]);
+    if (this.ws) try { this.ws.close(); } catch (e) { /* ignore */ }
+  }
+
+  getState(mac, erd) {
+    const m = this.state.get(mac);
+    return m ? m[C.normErd(erd)] : undefined;
+  }
+
+  async _connect(viaRefresh) {
+    if (this.stopped || this.connecting) return;
+    this.connecting = true;
+    if (this._timers.reconnect) { clearTimeout(this._timers.reconnect); this._timers.reconnect = null; }
+    try {
+      // 1. token
+      if (viaRefresh && this.refreshToken) {
+        this.log.debug('refreshing token');
+        try { this._setToken(await auth.refresh(this.refreshToken)); }
+        catch (e) { if (e.invalidGrant) { this.log.info('refresh token expired, full re-login'); this._setToken(await auth.login(this.username, this.password)); } else throw e; }
+      } else {
+        this.log.debug('logging in to SmartHQ');
+        this._setToken(await auth.login(this.username, this.password));
+      }
+      // 2. websocket credentials
+      const creds = (await axios.get(`${C.API_URL}/v1/websocket`, { headers: { authorization: `Bearer ${this.token}` }, timeout: 30000, validateStatus: () => true }));
+      if (creds.status >= 400 || !creds.data || !creds.data.endpoint) {
+        if (creds.status === 401 || creds.status === 403) { this.token = null; this.refreshToken = null; }
+        throw new Error(`GET /v1/websocket -> ${creds.status}`);
+      }
+      this.endpoint = creds.data.endpoint;
+      this.userId = creds.data.userId;
+      // 3. connect
+      this._openSocket();
+    } catch (e) {
+      this.connecting = false;
+      this.log.warn(`connect failed: ${e.message}`);
+      this._scheduleReconnect();
+    }
+  }
+
+  _setToken(tok) {
+    this.token = tok.access_token;
+    if (tok.refresh_token) this.refreshToken = tok.refresh_token;
+    const ms = ((tok.expires_in || 3600) * 1000) - C.REFRESH_SKEW_MS;
+    if (this._timers.refresh) clearTimeout(this._timers.refresh);
+    this._timers.refresh = setTimeout(() => { this.log.debug('token refresh timer'); this._reconnect(true); }, Math.max(ms, 60000));
+  }
+
+  _openSocket() {
+    const ws = new WebSocket(this.endpoint);
+    this.ws = ws;
+    ws.on('open', () => {
+      this.connecting = false;
+      this.reconnectDelay = C.RECONNECT_BASE_MS;
+      this.log.info('SmartHQ websocket connected');
+      this.emit('status', 'connected');
+      this._send({ kind: 'websocket#subscribe', action: 'subscribe', resources: ['/appliance/*/erd/*'] });
+      this._send(this._api('GET', '/v1/appliance', 'List-appliances'));
+      if (this._timers.keepalive) clearInterval(this._timers.keepalive);
+      this._timers.keepalive = setInterval(() => this._send({ kind: 'websocket#ping', id: 'keepalive-ping', action: 'ping' }), C.KEEPALIVE_MS);
+      if (this._timers.relist) clearInterval(this._timers.relist);
+      this._timers.relist = setInterval(() => this._send(this._api('GET', '/v1/appliance', 'List-appliances')), C.RELIST_MS);
+    });
+    ws.on('message', (raw) => { try { this._process(JSON.parse(raw.toString())); } catch (e) { this.log.debug(`msg parse: ${e.message}`); } });
+    ws.on('error', (e) => this.log.debug(`ws error: ${e.message}`));
+    ws.on('close', () => {
+      this.connecting = false;
+      if (this._timers.keepalive) { clearInterval(this._timers.keepalive); this._timers.keepalive = null; }
+      if (this._timers.relist) { clearInterval(this._timers.relist); this._timers.relist = null; }
+      if (this.ws === ws) this.ws = null;
+      if (!this.stopped) { this.emit('status', 'disconnected'); this.log.warn('SmartHQ websocket closed; reconnecting'); this._scheduleReconnect(); }
+    });
+  }
+
+  _reconnect(viaRefresh) {
+    if (this.ws) { try { this.ws.close(); } catch (e) { /* ignore */ } }
+    this._viaRefresh = viaRefresh;
+    if (!this.connecting) this._scheduleReconnect();
+  }
+
+  _scheduleReconnect() {
+    if (this.stopped || this._timers.reconnect) return;
+    const delay = this.reconnectDelay;
+    this.reconnectDelay = Math.min(this.reconnectDelay * 2, C.RECONNECT_MAX_MS);
+    this._timers.reconnect = setTimeout(() => { this._timers.reconnect = null; this._connect(this._viaRefresh !== false); }, delay);
+  }
+
+  _api(method, path, id, body) {
+    const m = { kind: 'websocket#api', action: 'api', host: C.API_HOST, method, path, id };
+    if (body) m.body = body;
+    return m;
+  }
+
+  _send(obj) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return false;
+    try { this.ws.send(JSON.stringify(obj)); return true; } catch (e) { this.log.debug(`send failed: ${e.message}`); return false; }
+  }
+
+  _process(m) {
+    if ((m.code === 401 || m.code === 403) || m.reason === 'Access token expired') { this.log.info('socket auth expired; refreshing'); this.token = null; this._reconnect(true); return; }
+    const kind = m.kind;
+    if (kind === 'websocket#api' && m.body && m.body.kind === 'appliance#applianceList') {
+      const items = m.body.items || [];
+      this.emit('appliances', items);
+      for (const it of items) this._send(this._api('GET', `/v1/appliance/${it.applianceId}/erd`, `${it.applianceId}-allErd`));
+      return;
+    }
+    if (kind === 'websocket#api' && m.body && m.body.kind === 'appliance#erdList') {
+      // id is "{mac}-allErd"
+      const mac = (m.id || '').replace(/-allErd$/, '');
+      for (const it of (m.body.items || [])) this._apply(mac, it.erd, it.value);
+      return;
+    }
+    if (kind === 'publish#erd' && m.item) {
+      this._apply(m.item.applianceId, m.item.erd, m.item.value);
+      return;
+    }
+    if (kind === 'websocket#api' && typeof m.id === 'string' && m.id.includes('-setErd-')) {
+      const p = this.pending.get(m.id);
+      if (p) {
+        this.pending.delete(m.id);
+        clearTimeout(p.timer);
+        const ok = (m.success === undefined || m.success === true) && (m.code === undefined || m.code === 200);
+        if (ok) p.resolve(); else p.reject(new Error(`setErd rejected: code=${m.code} success=${m.success}`));
+      }
+      return;
+    }
+  }
+
+  _apply(mac, erd, value) {
+    if (!mac) return;
+    const e = C.normErd(erd);
+    let s = this.state.get(mac);
+    if (!s) { s = {}; this.state.set(mac, s); }
+    if (s[e] === value) return;
+    s[e] = value;
+    this.emit('erd', mac, e, value);
+  }
+
+  // setErd over the websocket; resolves on backend ack. Optimistically applies locally for snappy UI.
+  setErd(mac, erd, value) {
+    const e = C.normErd(erd);
+    const id = `${mac}-setErd-${e}`;
+    const body = { kind: 'appliance#erdListEntry', userId: this.userId, applianceId: mac, erd: e, value, ackTimeout: 10, delay: 0 };
+    const sent = this._send(this._api('POST', `/v1/appliance/${mac}/erd/${e}`, id, body));
+    if (!sent) return Promise.reject(new Error('websocket not connected'));
+    this._apply(mac, e, value); // optimistic; publish#erd will confirm/correct
+    return new Promise((resolve, reject) => {
+      const old = this.pending.get(id);
+      if (old) { clearTimeout(old.timer); old.reject(new Error('superseded')); }
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error('setErd ack timeout')); }, C.SETERD_ACK_TIMEOUT_MS);
+      this.pending.set(id, { resolve, reject, timer });
+    });
+  }
+}
+
+module.exports = { SmartHQClient };

package/lib/const.js

@@ -0,0 +1,57 @@
+'use strict';
+
+// Plugin identity
+const PLUGIN_NAME = 'homebridge-ge-ac';
+const PLATFORM_NAME = 'GEProfileAC';
+
+// GE SmartHQ / Brillion endpoints + OAuth client (from simbaja/gehome const.py)
+const LOGIN_URL = 'https://accounts.brillion.geappliances.com';
+const API_URL = 'https://api.brillion.geappliances.com';
+const API_HOST = 'api.brillion.geappliances.com';
+const CLIENT_ID = '564c31616c4f7474434b307435412b4d2f6e7672';
+const CLIENT_SECRET = '6476512b5246446d452f697154444941387052645938466e5671746e5847593d';
+const REDIRECT_URI = 'brillion.4e617a766474657344444e562b5935566e51324a://oauth/redirect';
+const REGION_COOKIE = 'us-east-1';
+
+// Timing
+const KEEPALIVE_MS = 30000;
+const RELIST_MS = 600000;
+const REFRESH_SKEW_MS = 120000;
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 60000;
+const SETERD_ACK_TIMEOUT_MS = 10000;
+
+// AC ERD codes (gehome canonical, normalized to "0x" + uppercase digits to match the wire)
+const ERD = {
+  TARGET_TEMP: '0x7003', // R/W 2-byte BE degrees F
+  OPERATION_MODE: '0x7A01', // R/W 1-byte enum
+  AMBIENT_TEMP: '0x7A02', // R   1-byte degrees F
+  POWER: '0x7A0F', // R/W "00"/"01"
+  FAN: '0x7A00', // R/W enum
+  TEMP_UNIT: '0x0007', // R   "00"=F "01"=C (panel only)
+  FILTER: '0x7A04', // R   "00"=ok "01"=change
+};
+
+const POWER = { OFF: '00', ON: '01' };
+const MODE = { COOL: '00', FAN_ONLY: '01', ENERGY_SAVER: '02', HEAT: '03', DRY: '04' };
+const FAN = { AUTO: '01', LOW: '02', MED: '04', HIGH: '08' };
+
+// encode/decode
+const decodeInt = (v) => {
+  const n = parseInt(v, 16);
+  return Number.isNaN(n) ? null : n;
+};
+const encodeTempF = (f) => Math.round(f).toString(16).padStart(4, '0').toLowerCase(); // 72 -> "0048"
+const fToC = (f) => (f - 32) * 5 / 9;
+const cToF = (c) => (c * 9 / 5) + 32;
+
+// normalize an erd code to the on-wire form "0x" + UPPER digits ("0x7A01")
+const normErd = (code) => code.toUpperCase().replace('0X', '0x');
+
+module.exports = {
+  PLUGIN_NAME, PLATFORM_NAME,
+  LOGIN_URL, API_URL, API_HOST, CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, REGION_COOKIE,
+  KEEPALIVE_MS, RELIST_MS, REFRESH_SKEW_MS, RECONNECT_BASE_MS, RECONNECT_MAX_MS, SETERD_ACK_TIMEOUT_MS,
+  ERD, POWER, MODE, FAN,
+  decodeInt, encodeTempF, fToC, cToF, normErd,
+};

package/lib/platform.js

@@ -0,0 +1,63 @@
+'use strict';
+const C = require('./const');
+const { SmartHQClient } = require('./client');
+const { ACAccessory } = require('./accessory');
+
+class GEACPlatform {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config || {};
+    this.api = api;
+    this.accessories = []; // restored from cache
+    this.configured = new Set();
+
+    const creds = this.config.credentials || {};
+    this.username = this.config.username || creds.username;
+    this.password = this.config.password || creds.password;
+    if (!this.username || !this.password) {
+      this.log.error('Missing SmartHQ username/password in config — plugin disabled.');
+      return;
+    }
+    this.client = new SmartHQClient(log, this.username, this.password);
+    this.client.on('appliances', (items) => this._setupAppliances(items));
+
+    this.api.on('didFinishLaunching', () => {
+      this.log.info('Starting GE SmartHQ client…');
+      this.client.start();
+    });
+    this.api.on('shutdown', () => { if (this.client) this.client.stop(); });
+  }
+
+  configureAccessory(accessory) { this.accessories.push(accessory); }
+
+  _setupAppliances(items) {
+    const wanted = (this.config.macAddress || '').toUpperCase().replace(/[^0-9A-F]/g, '');
+    let ac;
+    if (wanted) ac = items.find((i) => i.applianceId.toUpperCase().includes(wanted));
+    if (!ac) ac = items.find((i) => /air|cond|\bac\b/i.test(`${i.type} ${i.nickname}`));
+    if (!ac) ac = items[0];
+    if (!ac) { this.log.warn('No appliances found on SmartHQ account.'); return; }
+
+    const mac = ac.applianceId;
+    if (this.configured.has(mac)) return;
+    this.configured.add(mac);
+
+    const name = this.config.name || ac.nickname || 'Air Conditioner';
+    const uuid = this.api.hap.uuid.generate(`${C.PLUGIN_NAME}:${mac}`);
+    let accessory = this.accessories.find((a) => a.UUID === uuid);
+    if (accessory) {
+      this.log.info(`Restoring AC "${name}" (${mac}) from cache`);
+      accessory.context.mac = mac;
+      new ACAccessory(this, accessory, this.client, mac);
+    } else {
+      this.log.info(`Adding AC "${name}" (${mac})`);
+      accessory = new this.api.platformAccessory(name, uuid);
+      accessory.context.mac = mac;
+      new ACAccessory(this, accessory, this.client, mac);
+      this.api.registerPlatformAccessories(C.PLUGIN_NAME, C.PLATFORM_NAME, [accessory]);
+      this.accessories.push(accessory);
+    }
+  }
+}
+
+module.exports = { GEACPlatform };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "homebridge-ge-ac",
+  "displayName": "GE Profile AC (SmartHQ WebSocket)",
+  "version": "1.0.0",
+  "description": "Homebridge plugin for GE Profile / SmartHQ Wi-Fi window air conditioners, using the realtime WebSocket control channel for reliable setpoint/mode/fan control.",
+  "author": "Fabricore",
+  "license": "ISC",
+  "homepage": "https://github.com/fabricore-eng/homebridge-ge-ac#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fabricore-eng/homebridge-ge-ac.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fabricore-eng/homebridge-ge-ac/issues"
+  },
+  "main": "index.js",
+  "engines": {
+    "node": ">=18.0.0",
+    "homebridge": ">=1.6.0"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "homebridge",
+    "homekit",
+    "ge",
+    "ge-appliances",
+    "smarthq",
+    "air-conditioner"
+  ],
+  "files": [
+    "index.js",
+    "lib/",
+    "config.schema.json"
+  ],
+  "dependencies": {
+    "axios": "^1.7.0",
+    "cheerio": "^1.0.0",
+    "ws": "^8.18.0"
+  }
+}