homebridge-tuya-plus 3.14.0-dev.3 → 3.14.0-dev.5

package/lib/TuyaCloudMessaging.js

@@ -0,0 +1,232 @@
+'use strict';
+
+const EventEmitter = require('events');
+const crypto = require('crypto');
+
+/*
+ * TuyaCloudMessaging
+ * ------------------
+ * Optional realtime updates for cloud-backed devices, over Tuya's MQTT message
+ * service. ONE instance is shared by every cloud device on the same Tuya
+ * project (one broker connection delivers status for all of them); messages are
+ * fanned out to the right device by its `devId`.
+ *
+ * This is intentionally a best-effort accelerator layered on top of polling:
+ * if the optional `mqtt` package is missing, or the broker can't be reached, or
+ * a message can't be decrypted, nothing breaks — the devices simply keep
+ * polling. When it IS working, changes (including physical button presses and
+ * the rain sensor) show up in HomeKit within a second or two.
+ *
+ * The connection + AES-GCM message decryption are faithful to the
+ * actively-maintained `0x5e/homebridge-tuya-platform` (`src/core/TuyaOpenMQ.ts`),
+ * re-implemented here with Node's built-in `crypto`.
+ */
+
+const GCM_TAG_LENGTH = 16;
+const PROTOCOL_DEVICE_STATUS = 4;
+
+// `mqtt` is an OPTIONAL dependency: realtime is a bonus, polling is the
+// guarantee. Loading it lazily keeps the plugin LAN-first and lets it run in
+// environments where mqtt isn't (or can't be) installed.
+let mqtt = null;
+let mqttLoadError = null;
+try {
+    mqtt = require('mqtt');
+} catch (ex) {
+    mqttLoadError = ex;
+}
+
+class TuyaCloudMessaging extends EventEmitter {
+    constructor({api, log} = {}) {
+        super();
+        this.api = api;
+        this.log = log || console;
+
+        this.linkId = crypto.randomUUID(); // bare v4 UUID, reused across reconnects
+        this.client = null;
+        this.config = null;
+        this.connected = false;
+
+        this._handlers = new Map(); // devId -> [fn(status)]
+        this._renewTimer = null;
+        this._started = false;
+        this._stopped = false;
+
+        // EventEmitter with many devices listening to 'online'/'offline'.
+        this.setMaxListeners(0);
+    }
+
+    static isAvailable() {
+        return !!mqtt;
+    }
+
+    // Register a device's status handler and lazily start the shared connection.
+    subscribeDevice(devId, handler) {
+        const id = '' + devId;
+        if (!this._handlers.has(id)) this._handlers.set(id, []);
+        this._handlers.get(id).push(handler);
+        if (!this._started) this.start();
+    }
+
+    start() {
+        if (this._stopped || this._started) return;
+        this._started = true;
+
+        if (!mqtt) {
+            this.log.warn(`Tuya Cloud realtime disabled: the optional "mqtt" package is not installed${mqttLoadError ? ` (${mqttLoadError.message})` : ''}. Devices will poll instead. Install it with "npm install mqtt" in the plugin folder to enable instant updates.`);
+            return;
+        }
+
+        this._connect().catch(ex => {
+            this.log.warn(`Tuya Cloud realtime could not start (${ex.message}); devices will poll instead.`);
+            this._scheduleRenew(60);
+        });
+    }
+
+    async _connect() {
+        if (this._stopped) return;
+        this._teardownClient();
+
+        const cfg = await this.api.getMqttConfig(this.linkId);
+        this.config = cfg;
+
+        if (!cfg.url || !cfg.source_topic || !cfg.source_topic.device) {
+            throw new Error('incomplete MQTT config from Tuya');
+        }
+
+        const client = mqtt.connect(cfg.url, {
+            clientId: cfg.client_id,
+            username: cfg.username,
+            password: cfg.password
+        });
+
+        client.on('connect', () => {
+            this.connected = true;
+            client.subscribe(cfg.source_topic.device, err => {
+                if (err) this.log.debug(`Tuya Cloud realtime subscribe error: ${err.message}`);
+            });
+            this.log.info('Tuya Cloud realtime connected (MQTT).');
+            this.emit('online');
+        });
+        client.on('message', (topic, payload) => this._onMessage(topic, payload));
+        client.on('error', err => this.log.debug(`Tuya Cloud realtime error: ${err && err.message}`));
+        client.on('close', () => this._markOffline());
+        client.on('end', () => this._markOffline());
+
+        this.client = client;
+
+        // Broker credentials expire; renew them a minute early (mqtt.js handles
+        // transient drops on its own via auto-reconnect).
+        const ttl = parseInt(cfg.expire_time) || 7200;
+        this._scheduleRenew(Math.max(60, ttl - 60));
+    }
+
+    _markOffline() {
+        if (this.connected) {
+            this.connected = false;
+            this.emit('offline');
+        }
+    }
+
+    _scheduleRenew(seconds) {
+        if (this._renewTimer) clearTimeout(this._renewTimer);
+        if (this._stopped) return;
+        this._renewTimer = setTimeout(() => {
+            this._connect().catch(ex => {
+                this.log.debug(`Tuya Cloud realtime renew failed: ${ex.message}`);
+                this._scheduleRenew(60);
+            });
+        }, seconds * 1000);
+    }
+
+    _onMessage(topic, payload) {
+        let envelope;
+        try {
+            envelope = JSON.parse(payload.toString());
+        } catch (_) { return; }
+
+        const {protocol, data, t} = envelope;
+        if (!data) return;
+
+        let plaintext;
+        try {
+            plaintext = this._decrypt(data, this.config && this.config.password, t);
+        } catch (ex) {
+            this.log.debug(`Tuya Cloud realtime decrypt failed: ${ex.message}`);
+            return;
+        }
+
+        let msg;
+        try {
+            msg = JSON.parse(plaintext);
+        } catch (_) { return; }
+
+        // We only care about device status frames (protocol 4). Some firmwares
+        // omit `protocol`; in that case fall back to "has a status array".
+        if (protocol != null && protocol !== PROTOCOL_DEVICE_STATUS && !(msg && Array.isArray(msg.status))) return;
+
+        const devId = msg && (msg.devId || msg.devid || msg.dev_id);
+        const status = msg && msg.status;
+        if (!devId || !Array.isArray(status)) return;
+
+        const handlers = this._handlers.get('' + devId);
+        if (!handlers || !handlers.length) return;
+        handlers.forEach(fn => {
+            try { fn(status); } catch (ex) { this.log.debug(`Tuya Cloud realtime handler error: ${ex.message}`); }
+        });
+    }
+
+    // Decrypt the MQTT `data` field. msg_encrypted_version 2.0 → AES-128-GCM,
+    // 1.0 → AES-128-ECB. The AES key is the middle 16 chars of the broker
+    // password (NOT the project Access Secret).
+    _decrypt(data, password, t) {
+        const key = Buffer.from(('' + (password || '')).substring(8, 24), 'utf8');
+        const buf = Buffer.from(data, 'base64');
+
+        // GCM (v2.0) layout: [ivLen(4) BE][iv(ivLen)][ciphertext][tag(16)].
+        // Try it first; if the header doesn't look like a sane IV length, or
+        // auth fails, fall back to ECB (v1.0).
+        if (buf.length > 4 + GCM_TAG_LENGTH) {
+            const ivLen = buf.readUIntBE(0, 4);
+            if (ivLen >= 12 && ivLen <= 16 && (4 + ivLen + GCM_TAG_LENGTH) <= buf.length) {
+                try {
+                    const iv = buf.slice(4, 4 + ivLen);
+                    const ciphertext = buf.slice(4 + ivLen, buf.length - GCM_TAG_LENGTH);
+                    const tag = buf.slice(buf.length - GCM_TAG_LENGTH);
+                    const decipher = crypto.createDecipheriv('aes-128-gcm', key, iv);
+                    decipher.setAuthTag(tag);
+                    const aad = Buffer.allocUnsafe(6);
+                    aad.writeUIntBE(Number(t) || 0, 0, 6);
+                    decipher.setAAD(aad);
+                    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+                } catch (gcmEx) {
+                    // fall through to ECB
+                }
+            }
+        }
+
+        const decipher = crypto.createDecipheriv('aes-128-ecb', key, null);
+        return Buffer.concat([decipher.update(buf), decipher.final()]).toString('utf8');
+    }
+
+    _teardownClient() {
+        if (this.client) {
+            try {
+                this.client.removeAllListeners();
+                this.client.end(true);
+            } catch (_) { /* ignore */ }
+            this.client = null;
+        }
+        this.connected = false;
+    }
+
+    stop() {
+        this._stopped = true;
+        if (this._renewTimer) { clearTimeout(this._renewTimer); this._renewTimer = null; }
+        this._teardownClient();
+    }
+}
+
+// Expose for unit tests / encryption round-trips.
+TuyaCloudMessaging.GCM_TAG_LENGTH = GCM_TAG_LENGTH;
+module.exports = TuyaCloudMessaging;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.3",
+  "version": "3.14.0-dev.5",
   "description": "A community-maintained Homebridge plugin for controlling Tuya devices locally over LAN. Includes new features, fixes, and updated device support.",
   "main": "index.js",
   "scripts": {
@@ -31,6 +31,9 @@
     "qrcode": "^1.4.1",
     "yaml": "^1.6.0"
   },
+  "optionalDependencies": {
+    "mqtt": "^5.15.1"
+  },
   "keywords": [
     "homebridge-plugin",
     "homebridge",

package/test/IrrigationSystemAccessory.test.js

@@ -444,3 +444,52 @@ describe('IrrigationSystemAccessory — rain mapping', () => {
         expect(instance._rainDetected('no_rain')).toBe(false);
     });
 });
+
+describe('IrrigationSystemAccessory — cloud mode (data-points keyed by code)', () => {
+    // Mirrors a real Tuya "sfkzq" watering controller reached over the cloud:
+    // valves are switch_1..4, battery is battery_percentage, and there is no
+    // rain sensor.
+    const cloudState = () => ({ switch_1: false, switch_2: false, switch_3: false, switch_4: false, battery_percentage: 99 });
+    const cloudCtx = { cloud: true, noRainSensor: true };
+
+    beforeEach(() => jest.useFakeTimers());
+    afterEach(() => { jest.clearAllTimers(); jest.useRealTimers(); });
+
+    test('default valves use Tuya codes switch_1..switch_4 (not numeric ids)', () => {
+        const { accessory } = makeHarness(cloudState(), cloudCtx);
+        ['switch_1', 'switch_2', 'switch_3', 'switch_4'].forEach(code => {
+            expect(valve(accessory, code)).toBeTruthy();
+        });
+        expect(valve(accessory, '1')).toBeFalsy();
+    });
+
+    test('turning a zone on writes the code/value to the device', () => {
+        const { accessory, device } = makeHarness(cloudState(), cloudCtx);
+        valve(accessory, 'switch_1').getCharacteristic(Characteristic.Active).triggerSet(1);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledWith({ switch_1: true });
+    });
+
+    test('battery is read from the battery_percentage code', () => {
+        const { accessory } = makeHarness(cloudState(), cloudCtx);
+        const battery = accessory.getService(Service.Battery);
+        expect(battery.getCharacteristic(Characteristic.BatteryLevel).value).toBe(99);
+    });
+
+    test('a realtime change keyed by code is reflected in HomeKit', () => {
+        const { accessory, device } = makeHarness(cloudState(), cloudCtx);
+        device.emitChange({ switch_2: true });
+        expect(valve(accessory, 'switch_2').getCharacteristic(Characteristic.Active).value).toBe(Characteristic.Active.ACTIVE);
+    });
+
+    test('an explicit valve list may use custom codes', () => {
+        const { accessory, device } = makeHarness(
+            { zone_a: false, zone_b: false, battery_percentage: 50 },
+            { cloud: true, noRainSensor: true, valves: [{ name: 'A', dp: 'zone_a' }, { name: 'B', dp: 'zone_b' }] }
+        );
+        expect(valve(accessory, 'zone_a')).toBeTruthy();
+        valve(accessory, 'zone_b').getCharacteristic(Characteristic.Active).triggerSet(1);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledWith({ zone_b: true });
+    });
+});

package/test/TuyaCloudApi.test.js

@@ -0,0 +1,196 @@
+'use strict';
+
+const crypto = require('crypto');
+const TuyaCloudApi = require('../lib/TuyaCloudApi');
+
+const EMPTY_SHA = crypto.createHash('sha256').update('').digest('hex');
+const md5 = s => crypto.createHash('md5').update(s).digest('hex');
+const hmacUpper = (str, key) => crypto.createHmac('sha256', key).update(str, 'utf8').digest('hex').toUpperCase();
+
+const ACCESS_ID = 'aid123';
+const ACCESS_KEY = 'secretKey456';
+
+const makeApi = (extra = {}) => new TuyaCloudApi({accessId: ACCESS_ID, accessKey: ACCESS_KEY, ...extra});
+
+describe('TuyaCloudApi — configuration', () => {
+    test('resolves region to a known endpoint', () => {
+        expect(makeApi({region: 'eu'}).endpoint).toBe('https://openapi.tuyaeu.com');
+        expect(makeApi({region: 'us'}).endpoint).toBe('https://openapi.tuyaus.com');
+        expect(makeApi({region: 'in'}).endpoint).toBe('https://openapi.tuyain.com');
+    });
+
+    test('unknown region falls back to US', () => {
+        expect(makeApi({region: 'nowhere'}).endpoint).toBe('https://openapi.tuyaus.com');
+    });
+
+    test('explicit endpoint wins and trailing slashes are trimmed', () => {
+        expect(makeApi({endpoint: 'https://example.com/'}).endpoint).toBe('https://example.com');
+    });
+
+    test('isConfigured reflects presence of credentials', () => {
+        expect(makeApi().isConfigured()).toBe(true);
+        expect(new TuyaCloudApi({}).isConfigured()).toBe(false);
+    });
+
+    test('keyFor is stable and distinguishes accounts', () => {
+        const a = TuyaCloudApi.keyFor({accessId: 'x', region: 'eu'});
+        const b = TuyaCloudApi.keyFor({accessId: 'x', region: 'eu'});
+        const c = TuyaCloudApi.keyFor({accessId: 'x', region: 'eu', username: 'u'});
+        expect(a).toBe(b);
+        expect(a).not.toBe(c);
+    });
+});
+
+describe('TuyaCloudApi — request signing', () => {
+    test('business signature folds in the access token and sets the header', () => {
+        const api = makeApi({region: 'eu'});
+        api._token = 'TOK';
+        const t = '1700000000000';
+        const nonce = 'nonce-1';
+        const h = api._signedHeaders({method: 'GET', urlPath: '/v1.0/devices/d/status', bodyStr: '', withToken: true, t, nonce});
+
+        const stringToSign = ['GET', EMPTY_SHA, '', '/v1.0/devices/d/status'].join('\n');
+        const expected = hmacUpper(ACCESS_ID + 'TOK' + t + nonce + stringToSign, ACCESS_KEY);
+
+        expect(h.sign).toBe(expected);
+        expect(h.access_token).toBe('TOK');
+        expect(h.client_id).toBe(ACCESS_ID);
+        expect(h.sign_method).toBe('HMAC-SHA256');
+        expect(h.t).toBe(t);
+        expect(h.nonce).toBe(nonce);
+    });
+
+    test('token signature omits the access token entirely', () => {
+        const api = makeApi();
+        api._token = 'SHOULD_NOT_APPEAR';
+        const t = '1700000000000';
+        const nonce = 'nonce-2';
+        const h = api._signedHeaders({method: 'GET', urlPath: '/v1.0/token?grant_type=1', bodyStr: '', withToken: false, t, nonce});
+
+        const stringToSign = ['GET', EMPTY_SHA, '', '/v1.0/token?grant_type=1'].join('\n');
+        const expected = hmacUpper(ACCESS_ID + t + nonce + stringToSign, ACCESS_KEY);
+
+        expect(h.sign).toBe(expected);
+        expect(h.access_token).toBeUndefined();
+    });
+
+    test('a request body changes the Content-SHA256 portion of the signature', () => {
+        const api = makeApi();
+        api._token = 'TOK';
+        const t = '1700000000000';
+        const nonce = 'n';
+        const body = JSON.stringify({commands: [{code: 'switch_1', value: true}]});
+        const h = api._signedHeaders({method: 'POST', urlPath: '/p', bodyStr: body, withToken: true, t, nonce});
+
+        const contentSha = crypto.createHash('sha256').update(body, 'utf8').digest('hex');
+        const stringToSign = ['POST', contentSha, '', '/p'].join('\n');
+        const expected = hmacUpper(ACCESS_ID + 'TOK' + t + nonce + stringToSign, ACCESS_KEY);
+        expect(h.sign).toBe(expected);
+        expect(contentSha).not.toBe(EMPTY_SHA);
+    });
+});
+
+describe('TuyaCloudApi — auth flow selection', () => {
+    test('custom project uses grant_type=1', async () => {
+        const api = makeApi();
+        const calls = [];
+        api._httpsRequest = async (method, path) => {
+            calls.push({method, path});
+            return {success: true, result: {access_token: 'T', uid: 'U', expire_time: 7200}};
+        };
+        const token = await api._ensureToken();
+        expect(token).toBe('T');
+        expect(api.uid).toBe('U');
+        expect(calls[0].path).toBe('/v1.0/token?grant_type=1');
+        expect(calls[0].method).toBe('GET');
+    });
+
+    test('smart-home project posts an MD5 password to authorized-login', async () => {
+        const api = makeApi({username: 'joe@example.com', password: 'pw', countryCode: '48', schema: 'tuyaSmart'});
+        let captured;
+        api._httpsRequest = async (method, path, headers, bodyStr) => {
+            captured = {method, path, bodyStr};
+            return {success: true, result: {access_token: 'T2', uid: 'U2', expire_time: 7200}};
+        };
+        const token = await api._ensureToken();
+        expect(token).toBe('T2');
+        expect(api.uid).toBe('U2');
+        expect(captured.path).toBe('/v1.0/iot-01/associated-users/actions/authorized-login');
+        const body = JSON.parse(captured.bodyStr);
+        expect(body.username).toBe('joe@example.com');
+        expect(body.password).toBe(md5('pw'));
+        expect(body.country_code).toBe('48');
+        expect(body.schema).toBe('tuyaSmart');
+    });
+});
+
+describe('TuyaCloudApi — endpoints', () => {
+    const ready = () => {
+        const api = makeApi();
+        api._token = 'TOK';
+        api._tokenExpiry = Date.now() + 1e6; // skip token fetch
+        return api;
+    };
+
+    test('getStatus returns the result array', async () => {
+        const api = ready();
+        api._httpsRequest = async () => ({success: true, result: [{code: 'switch_1', value: true}]});
+        await expect(api.getStatus('dev')).resolves.toEqual([{code: 'switch_1', value: true}]);
+    });
+
+    test('sendCommands posts the commands and reports success', async () => {
+        const api = ready();
+        let captured;
+        api._httpsRequest = async (method, path, headers, bodyStr) => {
+            captured = {method, path, body: JSON.parse(bodyStr)};
+            return {success: true, result: true};
+        };
+        const ok = await api.sendCommands('dev', [{code: 'switch_1', value: true}]);
+        expect(ok).toBe(true);
+        expect(captured.method).toBe('POST');
+        expect(captured.path).toBe('/v1.0/devices/dev/commands');
+        expect(captured.body).toEqual({commands: [{code: 'switch_1', value: true}]});
+    });
+
+    test('sendCommands short-circuits on an empty command list', async () => {
+        const api = ready();
+        api._httpsRequest = jest.fn();
+        await expect(api.sendCommands('dev', [])).resolves.toBe(true);
+        expect(api._httpsRequest).not.toHaveBeenCalled();
+    });
+
+    test('getMqttConfig posts the expected body and returns the broker config', async () => {
+        const api = ready();
+        api.uid = 'UID';
+        let captured;
+        api._httpsRequest = async (method, path, headers, bodyStr) => {
+            captured = {path, body: JSON.parse(bodyStr)};
+            return {success: true, result: {url: 'ssl://m1:8883', source_topic: {device: 't'}}};
+        };
+        const cfg = await api.getMqttConfig('link-1');
+        expect(captured.path).toBe('/v1.0/iot-03/open-hub/access-config');
+        expect(captured.body).toEqual({uid: 'UID', link_id: 'link-1', link_type: 'mqtt', topics: 'device', msg_encrypted_version: '2.0'});
+        expect(cfg.url).toBe('ssl://m1:8883');
+    });
+
+    test('an invalid-token error refreshes the token and retries once', async () => {
+        const api = ready();
+        let business = 0;
+        api._httpsRequest = async (method, path) => {
+            // The retry re-fetches a token; serve that separately.
+            if (path.startsWith('/v1.0/token')) return {success: true, result: {access_token: 'TOK2', expire_time: 7200}};
+            business++;
+            if (business === 1) return {success: false, code: 1010, msg: 'token invalid'};
+            return {success: true, result: 'ok'};
+        };
+        const res = await api.request('GET', '/x');
+        expect(business).toBe(2);
+        expect(res.result).toBe('ok');
+    });
+
+    test('a non-token error rejects', async () => {
+        const api = ready();
+        api._httpsRequest = async () => ({success: false, code: 28841002, msg: 'no permissions'});
+        await expect(api.request('GET', '/x')).rejects.toThrow(/no permissions/);
+    });
+});

package/test/TuyaCloudDevice.test.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const EventEmitter = require('events');
+const TuyaCloudDevice = require('../lib/TuyaCloudDevice');
+
+const log = {info: () => {}, warn: () => {}, error: () => {}, debug: () => {}};
+
+function makeApi(status = [{code: 'switch_1', value: false}, {code: 'battery_percentage', value: 99}]) {
+    return {
+        isConfigured: () => true,
+        getStatus: jest.fn().mockResolvedValue(status),
+        sendCommands: jest.fn().mockResolvedValue(true)
+    };
+}
+
+function makeDevice(api, messaging = null, extra = {}) {
+    return new TuyaCloudDevice({
+        cloudApi: api, messaging, log,
+        id: 'dev1', name: 'Sprinklers', type: 'irrigationsystem', cloud: true,
+        connect: false, ...extra
+    });
+}
+
+describe('TuyaCloudDevice', () => {
+    test('connect reads status and emits connect then change (state keyed by code)', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+
+        const events = [];
+        dev.on('connect', () => events.push('connect'));
+        dev.on('change', (changes, state) => events.push({changes, state}));
+
+        await dev._connect();
+
+        expect(dev.connected).toBe(true);
+        expect(dev.state).toEqual({switch_1: false, battery_percentage: 99});
+        expect(events[0]).toBe('connect');
+        expect(events[1].state).toEqual({switch_1: false, battery_percentage: 99});
+        expect(api.getStatus).toHaveBeenCalledWith('dev1');
+    });
+
+    test('update sends code/value commands and does NOT mutate local state', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        const before = {...dev.state};
+        dev.update({switch_1: true});
+
+        expect(api.sendCommands).toHaveBeenCalledWith('dev1', [{code: 'switch_1', value: true}]);
+        expect(dev.state).toEqual(before); // optimism lives in the accessory, not here
+    });
+
+    test('update is a no-op (no throw) before connect', () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        expect(dev.connected).toBe(false);
+        expect(() => dev.update({switch_1: true})).not.toThrow();
+        expect(api.sendCommands).not.toHaveBeenCalled();
+    });
+
+    test('applyStatus emits only the changed data-points', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        const changes = [];
+        dev.on('change', c => changes.push(c));
+
+        dev._applyStatus([{code: 'switch_1', value: true}, {code: 'battery_percentage', value: 99}]);
+        expect(changes).toHaveLength(1);
+        expect(changes[0]).toEqual({switch_1: true}); // battery unchanged → not emitted
+        expect(dev.state.switch_1).toBe(true);
+
+        changes.length = 0;
+        dev._applyStatus([{code: 'switch_1', value: true}]); // nothing changed
+        expect(changes).toHaveLength(0);
+    });
+
+    test('subscribes to realtime and re-reads state when the stream (re)connects', async () => {
+        const api = makeApi();
+        const messaging = Object.assign(new EventEmitter(), {
+            connected: false,
+            subscribeDevice: jest.fn()
+        });
+        const dev = makeDevice(api, messaging);
+        await dev._connect();
+
+        expect(messaging.subscribeDevice).toHaveBeenCalledWith('dev1', expect.any(Function));
+
+        // A realtime message routed back to the device updates its state.
+        const handler = messaging.subscribeDevice.mock.calls[0][1];
+        const changes = [];
+        dev.on('change', c => changes.push(c));
+        handler([{code: 'switch_2', value: true}]);
+        expect(dev.state.switch_2).toBe(true);
+        expect(changes[0]).toEqual({switch_2: true});
+
+        // On 'online' the device re-reads the full state (catch-up).
+        api.getStatus.mockClear();
+        messaging.emit('online');
+        await new Promise(r => setImmediate(r));
+        expect(api.getStatus).toHaveBeenCalledWith('dev1');
+    });
+});