@homebridge-plugins/homebridge-govee 11.32.2-beta.7 → 11.32.2-beta.9

package/CHANGELOG.md

@@ -20,6 +20,8 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - feat: add the H7103 and H7112 fans and the H5085 plug, with unknown controls saying so instead of guessing
 - feat: give every appliance type a starting handler, so a new model works for on and off and asks for the rest
 - refactor: point models that behave identically at one shared handler instead of copies of the same file
+- fix: stop shipping the test files to npm, since they are only needed in the repository
+- docs: keep the structure notes outside the repository, since they are working notes rather than plugin documentation
 
 ## v11.32.1 (2026-08-02)
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@homebridge-plugins/homebridge-govee",
   "alias": "Govee",
   "type": "module",
-  "version": "11.32.2-beta.7",
+  "version": "11.32.2-beta.9",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",

package/CONTRIBUTING-STRUCTURE.md

@@ -1,66 +0,0 @@
-# How this plugin is put together, and how to extend it
-
-This is the working reference for adding models and functionality. It exists so
-that the next change follows the same shape as the last, whoever makes it.
-
-## The three ways a model gets support
-
-**1. It shares behaviour with a model already handled — alias it.**
-Nothing new is written. `lib/device/index.js` maps the new model's key to the
-existing handler:
-
-```text
-deviceHumidifierH7147: deviceHumidifierH7143,
-```
-
-This is the common case. Several Govee models are the same device with a
-different name, and a handler copied per model is a handler that has to be fixed
-per model.
-
-**2. It is a new model of a known type, but the details are unknown — let it
-say so.** Add it to the model list in `lib/utils/constants.js` and nothing else.
-The dispatch falls back to `appliance-basic.js`, which offers on and off (that
-command is identical across every Govee appliance) and makes every other control
-report what it needs and then fail, so the owner sees it in the Home app, checks
-the log, and finds a line to paste into an issue.
-
-**3. It genuinely behaves differently — write a handler.**
-Only when the controls or their commands really differ.
-
-## Where model knowledge lives
-
-Per-model differences belong in data, not in a copied file:
-
-| File | Holds |
-|---|---|
-| `lib/utils/constants.js` | which models are which type |
-| `lib/utils/device-capabilities.js` | protocol quirks — colour command, brightness scale, and firmware-dependent behaviour |
-| `lib/utils/appliance-capabilities.js` | which controls a model actually has |
-
-If a change means copying a file and editing two lines, it belongs in one of
-these instead.
-
-## Reporting anything unknown
-
-Never log an unrecognised payload by hand. Use `lib/utils/report-unknown.js`:
-
-- `logUnknownData` — something arrived that is not understood
-- `reportUnsupportedControl` — the user asked for something not worked out yet
-
-Both produce one line carrying the model, firmware, hardware, connection and
-payload, so a single copy-paste is enough to act on. Both warn once and then
-drop to debug, so a device repeating itself does not flood the log.
-
-## Things worth knowing before changing appliance code
-
-- **The power command is universal.** `33 01 01` on, `33 01 00` off, on every
-  appliance. Safe to send for an untested model.
-- **Frames are 20 bytes with an XOR checksum** — byte 20 is the XOR of bytes
-  1–19. All 407 shipped appliance commands have been verified against this.
-- **A control that silently does nothing is worse than one that fails.** Failing
-  shows up in the Home app and sends the owner to the log.
-- **Do not remove a control a model has offered for a long time** on evidence
-  alone. Someone may be using it. Confirm with an owner first.
-- **HomeKit tiles have requirements.** A humidifier must report a current
-  humidity, which many Govee humidifiers never send — hence the plain fan tile
-  by default, and the richer one only when the device says it has the sensor.

package/lib/device/appliance-basic.test.js

@@ -1,150 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-import { resetReportedUnknowns } from '../utils/report-unknown.js'
-import { deviceHumidifierBasic, devicePurifierBasic } from './appliance-basic.js'
-
-/**
- * Minimal stand-ins for the HomeKit objects. Enough to see which service a
- * device is given and which controls it ends up with.
- */
-function makeCharacteristic(value) {
-  return {
-    value,
-    onSet(fn) {
-      this.setHandler = fn
-      return this
-    },
-    setProps() {
-      return this
-    },
-  }
-}
-
-function makeService(name) {
-  const chars = new Map()
-  return {
-    name,
-    getCharacteristic(char) {
-      if (!chars.has(char)) {
-        chars.set(char, makeCharacteristic(char === 'On' ? false : 0))
-      }
-      return chars.get(char)
-    },
-    updateCharacteristic(char, value) {
-      this.getCharacteristic(char).value = value
-      return this
-    },
-    testCharacteristic: char => chars.has(char),
-    removeCharacteristic() {},
-    chars,
-  }
-}
-
-function makePlatform() {
-  // Service and characteristic names stand in for themselves, so a test can
-  // assert on which one was picked
-  const proxy = new Proxy({}, { get: (_t, prop) => prop })
-  return {
-    log: Object.assign(vi.fn(), { warn: vi.fn(), debug: vi.fn() }),
-    api: { hap: { Service: proxy, Characteristic: proxy, HapStatusError: class {} } },
-  }
-}
-
-function makeAccessory(capabilities) {
-  const services = new Map()
-  return {
-    displayName: 'Test Appliance',
-    context: {
-      gvModel: 'H7146',
-      gvDeviceId: 'AA:BB',
-      openApiCapabilities: capabilities,
-    },
-    getService: name => services.get(name),
-    addService(name) {
-      const svc = makeService(name)
-      services.set(name, svc)
-      return svc
-    },
-    removeService(svc) {
-      services.delete(svc.name)
-    },
-    log: vi.fn(),
-    logWarn: vi.fn(),
-    logDebug: vi.fn(),
-    services,
-  }
-}
-
-describe('basic appliance handler', () => {
-  beforeEach(() => {
-    resetReportedUnknowns()
-  })
-
-  describe('choosing the tile for a humidifier', () => {
-    it('uses the plain fan when the device reports no humidity', () => {
-      // HomeKit's humidifier must show a current humidity, and many govee
-      // humidifiers never send one - so the safe tile is the plain fan
-      const accessory = makeAccessory({})
-      const device = new deviceHumidifierBasic(makePlatform(), accessory)
-
-      expect(device.service.name).toBe('Fan')
-      expect(accessory.services.has('HumidifierDehumidifier')).toBe(false)
-    })
-
-    it('uses the proper humidifier when the device does report humidity', () => {
-      const accessory = makeAccessory({ sensorHumidity: { type: 'sensor' } })
-      const device = new deviceHumidifierBasic(makePlatform(), accessory)
-
-      expect(device.service.name).toBe('HumidifierDehumidifier')
-    })
-
-    it('switches the power characteristic to suit the tile', () => {
-      // the plain fan switches on a boolean, the humidifier on active
-      const plain = new deviceHumidifierBasic(makePlatform(), makeAccessory({}))
-      const rich = new deviceHumidifierBasic(
-        makePlatform(),
-        makeAccessory({ sensorHumidity: {} }),
-      )
-
-      expect(plain.powerChar).toBe('On')
-      expect(plain.powerOn).toBe(true)
-      expect(rich.powerChar).toBe('Active')
-      expect(rich.powerOn).toBe(1)
-    })
-
-    it('passes a humidity reading through only on the richer tile', () => {
-      const rich = new deviceHumidifierBasic(
-        makePlatform(),
-        makeAccessory({ sensorHumidity: {} }),
-      )
-      rich.externalUpdate({ humidity: 55 })
-
-      expect(rich.service.getCharacteristic('CurrentRelativeHumidity').value).toBe(55)
-    })
-  })
-
-  it('keeps the current-state characteristic on a purifier', () => {
-    // the purifier has no fallback tile, so its state characteristic must stay
-    const device = new devicePurifierBasic(makePlatform(), makeAccessory({}))
-
-    expect(device.service.name).toBe('AirPurifier')
-    expect(device.currentStateChar).toBe('CurrentAirPurifierState')
-  })
-
-  it('reports an unknown control and fails the request', async () => {
-    const accessory = makeAccessory({})
-    const device = new deviceHumidifierBasic(makePlatform(), accessory)
-
-    await expect(device.internalVariableUpdate(50)).rejects.toBeDefined()
-    expect(accessory.logWarn).toHaveBeenCalledTimes(1)
-    expect(accessory.logWarn.mock.calls[0][0]).toContain('mist level')
-  })
-
-  it('ignores the control following the device being switched off', async () => {
-    const accessory = makeAccessory({})
-    const device = new deviceHumidifierBasic(makePlatform(), accessory)
-
-    await expect(device.internalVariableUpdate(0)).resolves.toBeUndefined()
-    expect(accessory.logWarn).not.toHaveBeenCalled()
-  })
-})

package/lib/utils/appliance-capabilities.test.js

@@ -1,31 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { getHeaterFeatures } from './appliance-capabilities.js'
-
-describe('appliance capabilities', () => {
-  describe('heaters', () => {
-    it('offers the full set to a model that is not described', () => {
-      // Anything not listed keeps what the shared handler has always offered,
-      // so adding an entry is opt-in and no existing model changes by accident
-      expect(getHeaterFeatures('H7130')).toEqual({ swing: true, lock: true })
-      expect(getHeaterFeatures('H713A')).toEqual({ swing: true, lock: true })
-    })
-
-    it('withholds controls the newer lite heaters do not have', () => {
-      expect(getHeaterFeatures('H7137')).toEqual({ swing: false, lock: false })
-      expect(getHeaterFeatures('H713E')).toEqual({ swing: false, lock: false })
-    })
-
-    it('copes with an unknown or missing model', () => {
-      expect(getHeaterFeatures('NOPE')).toEqual({ swing: true, lock: true })
-      expect(getHeaterFeatures(undefined)).toEqual({ swing: true, lock: true })
-    })
-
-    it('does not let a caller change the stored defaults', () => {
-      const features = getHeaterFeatures('H7130')
-      features.swing = false
-
-      expect(getHeaterFeatures('H7130').swing).toBe(true)
-    })
-  })
-})

package/lib/utils/ble-timeouts.test.js

@@ -1,44 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { BLE_STAGE_TIMEOUTS, BLE_UPDATE_TIMEOUT } from './ble-protocol.js'
-
-/**
- * The bug these guard against (#1328): the BLE connect timeout and the platform
- * queue timeout were both a flat 10000ms. The queue therefore killed a task at
- * the exact moment the connect gave up, and any light that connected slowly had
- * nothing left of the budget for discovering services and writing its command.
- */
-describe('bLE timeout budget', () => {
-  it('leaves room for every stage of an update', () => {
-    const stages = BLE_STAGE_TIMEOUTS.powerOn
-      + BLE_STAGE_TIMEOUTS.connect
-      + BLE_STAGE_TIMEOUTS.untimedStages
-      + BLE_STAGE_TIMEOUTS.write
-      + BLE_STAGE_TIMEOUTS.settle
-
-    expect(BLE_UPDATE_TIMEOUT).toBeGreaterThan(stages)
-  })
-
-  it('is not simply the connect timeout, which is what caused #1328', () => {
-    expect(BLE_UPDATE_TIMEOUT).not.toBe(BLE_STAGE_TIMEOUTS.connect)
-  })
-
-  it('still has time left after the slowest possible connect', () => {
-    // A connect that only just succeeds must leave enough behind to discover
-    // services and send the command - otherwise a slow device is
-    // indistinguishable from an unreachable one.
-    const afterSlowestConnect = BLE_UPDATE_TIMEOUT
-      - BLE_STAGE_TIMEOUTS.powerOn
-      - BLE_STAGE_TIMEOUTS.connect
-
-    expect(afterSlowestConnect).toBeGreaterThanOrEqual(
-      BLE_STAGE_TIMEOUTS.untimedStages + BLE_STAGE_TIMEOUTS.write + BLE_STAGE_TIMEOUTS.settle,
-    )
-  })
-
-  it('keeps every stage timeout positive', () => {
-    Object.entries(BLE_STAGE_TIMEOUTS).forEach(([stage, ms]) => {
-      expect(ms, stage).toBeGreaterThan(0)
-    })
-  })
-})

package/lib/utils/decode.test.js

@@ -1,105 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { decodeH5074Values, decodeH5075Values, decodeH5179Values } from './decode.js'
-
-/**
- * Helpers that build a advertisement exactly as the sensor would, so a decoder
- * is checked against a known reading rather than against itself.
- */
-function leHex(value) {
-  const v = value & 0xFFFF
-  return `${(v & 0xFF).toString(16).padStart(2, '0')}${((v >> 8) & 0xFF).toString(16).padStart(2, '0')}`
-}
-
-function byteHex(value) {
-  return value.toString(16).padStart(2, '0')
-}
-
-// H5074: temperature and humidity are little-endian pairs at bytes 3-4 and 5-6,
-// with the battery at byte 7
-function buildH5074(tempInC, humidity, battery) {
-  return `88ec00${leHex(Math.round(tempInC * 100))}${leHex(Math.round(humidity * 100))}${byteHex(battery)}00`
-}
-
-// H5179: same shape but shifted along, temperature at bytes 6-7, humidity at
-// bytes 8-9 and the battery at byte 10
-function buildH5179(tempInC, humidity, battery) {
-  return `0188ec000102${leHex(Math.round(tempInC * 100))}${leHex(Math.round(humidity * 100))}${byteHex(battery)}`
-}
-
-describe('bLE sensor decoding', () => {
-  describe('h5074', () => {
-    it('reads back a known reading', () => {
-      const result = decodeH5074Values(buildH5074(22.5, 45, 88))
-
-      expect(result.tempInC).toBe(22.5)
-      expect(result.humidity).toBe(45)
-      expect(result.battery).toBe(88)
-    })
-
-    it('handles a temperature below freezing', () => {
-      expect(decodeH5074Values(buildH5074(-5.25, 30, 50)).tempInC).toBe(-5.25)
-    })
-  })
-
-  describe('h5179', () => {
-    /**
-     * The bug this guards against: the temperature was built from the byte that
-     * actually holds the low half of the humidity, so a real 22.5C was reported
-     * as 21.96C. Wrong, but close enough to look believable, which is why it
-     * went unnoticed - hence a test that pins an exact expected value.
-     */
-    it('reads back a known reading', () => {
-      const result = decodeH5179Values(buildH5179(22.5, 45, 100))
-
-      expect(result.tempInC).toBe(22.5)
-      expect(result.humidity).toBe(45)
-      expect(result.battery).toBe(100)
-    })
-
-    it('handles a temperature below freezing', () => {
-      const result = decodeH5179Values(buildH5179(-3.5, 55.25, 20))
-
-      expect(result.tempInC).toBe(-3.5)
-      expect(result.humidity).toBe(55.25)
-    })
-
-    it('does not let the humidity change the temperature', () => {
-      // same temperature, different humidity - the temperature must not move
-      const a = decodeH5179Values(buildH5179(20, 30, 90))
-      const b = decodeH5179Values(buildH5179(20, 70, 90))
-
-      expect(a.tempInC).toBe(20)
-      expect(b.tempInC).toBe(20)
-    })
-
-    it('converts to fahrenheit from the corrected celsius', () => {
-      expect(decodeH5179Values(buildH5179(100, 50, 80)).tempInF).toBe(212)
-    })
-  })
-
-  describe('h5075', () => {
-    it('reads the temperature and humidity out of the shared packed value', () => {
-      // This model packs both readings into one 3-byte number, temperature
-      // scaled by 10000 with the humidity in the last three digits, so the two
-      // cannot be set independently the way they can on the models above.
-      const packed = 225450
-      const result = decodeH5075Values(`88ec00${packed.toString(16).padStart(6, '0')}58`)
-
-      expect(result.tempInC).toBe(22.545)
-      expect(result.humidity).toBe(45)
-      expect(result.battery).toBe(88)
-    })
-
-    it('reads a temperature below freezing from the sign bit', () => {
-      const packed = 0x800000 | 55000
-      const result = decodeH5075Values(`88ec00${packed.toString(16).padStart(6, '0')}58`)
-
-      expect(result.tempInC).toBe(-5.5)
-    })
-  })
-
-  it('rejects a stream that is too short to hold a reading', () => {
-    expect(() => decodeH5179Values('0188ec00')).toThrow()
-  })
-})

package/lib/utils/device-capabilities.test.js

@@ -1,62 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { COLOR_SUB } from './ble-protocol.js'
-import { getDeviceCapabilities } from './device-capabilities.js'
-
-/**
- * The bug these guard against (#1332): the H6102 was sent the 0x0D colour
- * command, which it accepts and then ignores, so on, off and brightness worked
- * while colour silently did nothing. Which colour command the strip wants
- * depends on its firmware, so the capability lookup has to take the version
- * into account rather than picking one for every H6102.
- */
-describe('device capabilities', () => {
-  it('gives an unlisted model the defaults', () => {
-    const caps = getDeviceCapabilities('H0000')
-
-    expect(caps.bleColorCmd).toEqual([COLOR_SUB.RGB_DEFAULT])
-    expect(caps.bleColorCmdSuffix).toEqual([])
-    expect(caps.bleBrightnessScale).toBe(0xFF)
-  })
-
-  describe('h6102 colour command by firmware', () => {
-    it('uses the extended command from 1.03.01 upwards', () => {
-      const caps = getDeviceCapabilities('H6102', '1.03.01')
-
-      expect(caps.bleColorCmd).toEqual(COLOR_SUB.RGB_EXTENDED)
-      expect(caps.bleColorCmdSuffix).toEqual([0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0x7F])
-    })
-
-    it('uses the extended command on later firmware too', () => {
-      expect(getDeviceCapabilities('H6102', '1.06.00').bleColorCmd).toEqual(COLOR_SUB.RGB_EXTENDED)
-    })
-
-    it('keeps the standard command below 1.03.01', () => {
-      const caps = getDeviceCapabilities('H6102', '1.02.99')
-
-      expect(caps.bleColorCmd).toEqual([COLOR_SUB.RGB_DEFAULT])
-      expect(caps.bleColorCmdSuffix).toEqual([])
-    })
-
-    it('keeps the standard command when the firmware is unknown', () => {
-      expect(getDeviceCapabilities('H6102').bleColorCmd).toEqual([COLOR_SUB.RGB_DEFAULT])
-    })
-
-    it('keeps the brightness scale whatever the firmware', () => {
-      expect(getDeviceCapabilities('H6102').bleBrightnessScale).toBe(0x64)
-      expect(getDeviceCapabilities('H6102', '1.06.00').bleBrightnessScale).toBe(0x64)
-    })
-  })
-
-  it('compares version parts as numbers, not text', () => {
-    // "1.10.00" is newer than "1.03.01" even though it sorts earlier as text
-    expect(getDeviceCapabilities('H6102', '1.10.00').bleColorCmd).toEqual(COLOR_SUB.RGB_EXTENDED)
-    // and a shorter string is padded rather than treated as newer
-    expect(getDeviceCapabilities('H6102', '1.3').bleColorCmd).toEqual([COLOR_SUB.RGB_DEFAULT])
-  })
-
-  it('leaves a firmware-gated model alone when another model matches', () => {
-    // the H617A is not firmware gated, so its override applies at any version
-    expect(getDeviceCapabilities('H617A', '1.00.00').bleColorCmd).toEqual(COLOR_SUB.RGB_EXTENDED)
-  })
-})

package/lib/utils/functions.test.js

@@ -1,292 +0,0 @@
-import { Buffer } from 'node:buffer'
-
-import { describe, expect, it } from 'vitest'
-
-import {
-  base64ToHex,
-  cenToFar,
-  describeControlFailure,
-  fanSpeedToHkPercent,
-  farToCen,
-  generateCodeFromHexValues,
-  getTwoItemPosition,
-  hasProperty,
-  hexToBase64,
-  hexToDecimal,
-  hexToTwoItems,
-  hkPercentToFanSpeed,
-  nearestHalf,
-  parseDeviceId,
-  parseError,
-  updateFailureError,
-} from './functions.js'
-
-/**
- * The fan speed mapping is the one worth pinning hardest. Before #1310/#1326
- * the plugin sent the raw HomeKit percentage as a speed, so a slider at 100%
- * asked an 8-step fan for speed 100, and the Home app displayed speeds like
- * "7%". These tests cover the round trip on both step counts we ship.
- */
-describe('fan speed mapping', () => {
-  it('maps the top of the slider to the fastest speed', () => {
-    expect(hkPercentToFanSpeed(100, 8)).toBe(8)
-    expect(hkPercentToFanSpeed(100, 12)).toBe(12)
-  })
-
-  it('never returns speed 0, which would mean "off" to the device', () => {
-    // HomeKit sends 0 when the fan is switched off. Speed 0 is not a valid
-    // speed, so the mapping clamps to the slowest instead.
-    expect(hkPercentToFanSpeed(0, 8)).toBe(1)
-    expect(hkPercentToFanSpeed(1, 8)).toBe(1)
-  })
-
-  it('never exceeds the number of steps the model has', () => {
-    expect(hkPercentToFanSpeed(150, 8)).toBe(8)
-  })
-
-  it('round trips every speed on an 8 step model', () => {
-    for (let speed = 1; speed <= 8; speed++) {
-      expect(hkPercentToFanSpeed(fanSpeedToHkPercent(speed, 8), 8)).toBe(speed)
-    }
-  })
-
-  it('round trips every speed on a 12 step model', () => {
-    for (let speed = 1; speed <= 12; speed++) {
-      expect(hkPercentToFanSpeed(fanSpeedToHkPercent(speed, 12), 12)).toBe(speed)
-    }
-  })
-
-  it('reports a stopped fan as 0 percent', () => {
-    expect(fanSpeedToHkPercent(0, 8)).toBe(0)
-    expect(fanSpeedToHkPercent(undefined, 8)).toBe(0)
-  })
-
-  it('shows auto mode at the top of the slider', () => {
-    // Chosen so the two paths disagree: without the auto case, speed 5 of 8
-    // would map to 63%. An auto speed that happens to sit above the step count
-    // would return 100 either way and would not prove the branch runs.
-    expect(fanSpeedToHkPercent(5, 8, 5)).toBe(100)
-    expect(fanSpeedToHkPercent(5, 8, undefined)).toBe(63)
-  })
-
-  it('does not treat auto as special when the model has no auto speed', () => {
-    expect(fanSpeedToHkPercent(4, 8, undefined)).toBe(50)
-  })
-})
-
-describe('parseDeviceId', () => {
-  it('uppercases and strips punctuation the api does not use', () => {
-    expect(parseDeviceId('ab:cd:ef')).toBe('AB:CD:EF')
-    expect(parseDeviceId('ab cd-ef')).toBe('ABCDEF')
-  })
-
-  it('keeps the separators govee device ids actually contain', () => {
-    // Colons and underscores are meaningful in a Govee device id, so the
-    // cleaner must not strip them along with the rest.
-    expect(parseDeviceId('AB:CD_EF')).toBe('AB:CD_EF')
-  })
-
-  it('accepts a non-string id without throwing', () => {
-    expect(parseDeviceId(123456)).toBe('123456')
-  })
-})
-
-describe('hex helpers', () => {
-  it('splits a hex string into byte pairs', () => {
-    expect(hexToTwoItems('aabbcc')).toEqual(['aa', 'bb', 'cc'])
-  })
-
-  it('reads a byte by its 1-based position, as the device handlers do', () => {
-    // Callers index from 1 because they are reading a protocol spec, not an
-    // array. Getting this off by one silently misreads every payload.
-    const parts = hexToTwoItems('aa1b0164')
-    expect(getTwoItemPosition(parts, 1)).toBe('aa')
-    expect(getTwoItemPosition(parts, 2)).toBe('1b')
-    expect(getTwoItemPosition(parts, 4)).toBe('64')
-  })
-
-  it('converts hex to decimal', () => {
-    expect(hexToDecimal('64')).toBe(100)
-    expect(hexToDecimal('ff')).toBe(255)
-  })
-
-  it('round trips base64 and hex', () => {
-    const hex = '330501000000000000000000000000000000000037'
-    expect(base64ToHex(hexToBase64(hex))).toBe(hex)
-  })
-})
-
-describe('generateCodeFromHexValues', () => {
-  it('builds a 20 byte packet', () => {
-    // Every Govee BLE/IoT command is exactly 20 bytes: 19 of payload plus a
-    // trailing XOR checksum.
-    const packet = Buffer.from(generateCodeFromHexValues(['0x33', '0x05', '0x01']), 'base64')
-    expect(packet).toHaveLength(20)
-  })
-
-  it('ends with an xor checksum over the first 19 bytes', () => {
-    const packet = Buffer.from(generateCodeFromHexValues(['0x33', '0x05', '0x01']), 'base64')
-    let expected = 0
-    for (let i = 0; i < 19; i++) {
-      expected ^= packet[i]
-    }
-    expect(packet[19]).toBe(expected)
-  })
-
-  it('pads short commands with zeroes rather than leaving them short', () => {
-    const packet = Buffer.from(generateCodeFromHexValues(['0x33', '0x01']), 'base64')
-    expect(packet.subarray(2, 19).every(b => b === 0)).toBe(true)
-  })
-})
-
-describe('temperature conversion', () => {
-  it('converts celsius to fahrenheit to one decimal place', () => {
-    expect(cenToFar(0)).toBe(32)
-    expect(cenToFar(100)).toBe(212)
-    expect(cenToFar(21.5)).toBe(70.7)
-  })
-
-  it('converts fahrenheit to whole celsius', () => {
-    expect(farToCen(32)).toBe(0)
-    expect(farToCen(212)).toBe(100)
-  })
-
-  it('rounds to the nearest half', () => {
-    expect(nearestHalf(21.24)).toBe(21)
-    expect(nearestHalf(21.26)).toBe(21.5)
-    expect(nearestHalf(21.75)).toBe(22)
-  })
-})
-
-describe('misc helpers', () => {
-  it('detects own properties only', () => {
-    expect(hasProperty({ a: 1 }, 'a')).toBe(true)
-    expect(hasProperty({}, 'toString')).toBe(false)
-  })
-
-  it('appends the first stack frame to an error message', () => {
-    const err = new Error('boom')
-    err.stack = 'Error: boom\n    at thing (/a.js:1:1)'
-    expect(parseError(err)).toContain('boom')
-    expect(parseError(err)).toContain('at thing')
-  })
-
-  it('can be told to hide the stack for expected errors', () => {
-    // Some errors are routine (a device being offline) and their stack is
-    // noise in the log, so callers pass them in hideStack.
-    const err = new Error('offline')
-    err.stack = 'Error: offline\n    at thing (/a.js:1:1)'
-    expect(parseError(err, ['offline'])).toBe('offline')
-  })
-})
-
-/**
- * Govee can accept a control request and still refuse the command, reporting it
- * only inside `capability.state`. That shape used to read as success, so the
- * device ignored the command while HomeKit kept showing the new state (#1324).
- */
-describe('describeControlFailure', () => {
-  it('returns govee\'s own wording for the offline water timer in #1324', () => {
-    const response = {
-      requestId: 'test-control-turn-on',
-      msg: 'Device is offline. Please check the Wi-Fi connection.',
-      code: 400,
-      capability: {
-        type: 'devices.capabilities.on_off',
-        instance: 'powerSwitch',
-        state: {
-          status: 'failure',
-          errorCode: 400,
-          errorMsg: 'Device is offline. Please check the Wi-Fi connection.',
-        },
-        value: 1,
-      },
-    }
-
-    expect(describeControlFailure(response)).toBe('Device is offline. Please check the Wi-Fi connection.')
-  })
-
-  it('catches a refusal even when the response is 200 overall', () => {
-    // The case the old code missed entirely: nothing at the top level says
-    // anything went wrong.
-    const response = {
-      code: 200,
-      msg: 'success',
-      capability: { state: { status: 'failure', errorMsg: 'Device is busy' } },
-    }
-
-    expect(describeControlFailure(response)).toBe('Device is busy')
-  })
-
-  it('falls back to the top-level message when no errorMsg is given', () => {
-    const response = {
-      msg: 'Device is offline',
-      capability: { state: { status: 'failure' } },
-    }
-
-    expect(describeControlFailure(response)).toBe('Device is offline')
-  })
-
-  it('still describes a refusal that carries no wording at all', () => {
-    expect(describeControlFailure({ capability: { state: { status: 'failure' } } }))
-      .toBe('the device rejected the command')
-  })
-
-  it('returns null when the command was accepted', () => {
-    const accepted = {
-      code: 200,
-      msg: 'success',
-      capability: { state: { status: 'success' } },
-    }
-
-    expect(describeControlFailure(accepted)).toBeNull()
-  })
-
-  it('returns null for responses with no capability state', () => {
-    expect(describeControlFailure({ code: 200, msg: 'success' })).toBeNull()
-    expect(describeControlFailure({})).toBeNull()
-    expect(describeControlFailure(undefined)).toBeNull()
-  })
-})
-
-/**
- * The bug (#1324): when a command had a Bluetooth fallback, every earlier
- * failure was thrown away and replaced with "no connection method available".
- * That is worse than vague — it is untrue, and its link sends the user off to
- * configure connection methods when the real answer was that Govee had said
- * the device was offline.
- */
-describe('updateFailureError', () => {
-  it('reports govee\'s own refusal rather than the generic message', () => {
-    const refusal = new Error('Device is offline. Please check the Wi-Fi connection.')
-    const chosen = updateFailureError(refusal, 'no connection method available')
-
-    expect(chosen.message).toBe('Device is offline. Please check the Wi-Fi connection.')
-  })
-
-  it('passes the original error through, so upstream flags survive', () => {
-    const refusal = new Error('Device is offline. Please check the Wi-Fi connection.')
-    refusal.deviceRefusal = true
-
-    const chosen = updateFailureError(refusal, 'no connection method available')
-
-    // Same object, not a copy - platform.js reads `deviceRefusal` off it to
-    // decide whether to print a stack line.
-    expect(chosen).toBe(refusal)
-    expect(chosen.deviceRefusal).toBe(true)
-  })
-
-  it('falls back to the generic message only when nothing was tried', () => {
-    expect(updateFailureError(undefined, 'no connection method available').message)
-      .toBe('no connection method available')
-    expect(updateFailureError(null, 'no connection method available').message)
-      .toBe('no connection method available')
-  })
-
-  it('keeps a bluetooth timeout rather than masking it', () => {
-    const bleFailure = new Error('BLE update failed: Connection timeout')
-
-    expect(updateFailureError(bleFailure, 'no connection method available').message)
-      .toBe('BLE update failed: Connection timeout')
-  })
-})

package/lib/utils/report-unknown.test.js

@@ -1,187 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-import { isFirstReport, logUnknownData, reportUnsupportedControl, resetReportedUnknowns } from './report-unknown.js'
-
-function makeAccessory(context = {}) {
-  return {
-    displayName: 'Test Device',
-    context: {
-      gvDeviceId: 'AA:BB:CC:DD',
-      gvModel: 'H6102',
-      firmware: '1.03.01',
-      hardware: '2.00.01',
-      ...context,
-    },
-    logWarn: vi.fn(),
-    logDebug: vi.fn(),
-  }
-}
-
-function reported(accessory) {
-  return accessory.logWarn.mock.calls[0]?.[0] ?? ''
-}
-
-function payloadOf(accessory) {
-  const line = reported(accessory)
-  return JSON.parse(line.slice(line.indexOf('{')))
-}
-
-describe('reporting unrecognised data', () => {
-  beforeEach(() => {
-    resetReportedUnknowns()
-  })
-
-  it('includes everything needed to add support, without being asked for it', () => {
-    const accessory = makeAccessory()
-
-    logUnknownData(accessory, {
-      kind: 'scene',
-      source: 'AWS',
-      raw: 'MwUBAQAAAAAAAAAAAAAAAAAAADY=',
-    })
-
-    const payload = payloadOf(accessory)
-
-    // the three things that otherwise always need a follow-up question
-    expect(payload.model).toBe('H6102')
-    expect(payload.firmware).toBe('1.03.01')
-    expect(payload.source).toBe('AWS')
-    // and the data itself, in both the forms that get used
-    expect(payload.raw).toBe('MwUBAQAAAAAAAAAAAAAAAAAAADY=')
-    expect(payload.hex).toBe('3305010100000000000000000000000000000036')
-  })
-
-  it('tells the user the line is what to report', () => {
-    const accessory = makeAccessory()
-    logUnknownData(accessory, { kind: 'scene', source: 'BLE', raw: 'abc' })
-
-    expect(reported(accessory)).toContain('please include this line if you report it')
-  })
-
-  it('is a warning the first time so it is actually seen', () => {
-    const accessory = makeAccessory()
-    logUnknownData(accessory, { kind: 'scene', source: 'AWS', raw: 'abc' })
-
-    expect(accessory.logWarn).toHaveBeenCalledTimes(1)
-    expect(accessory.logDebug).not.toHaveBeenCalled()
-  })
-
-  it('does not shout twice about the same payload', () => {
-    const accessory = makeAccessory()
-    const entry = { kind: 'scene', source: 'AWS', raw: 'abc' }
-
-    logUnknownData(accessory, entry)
-    logUnknownData(accessory, entry)
-    logUnknownData(accessory, entry)
-
-    // devices repeat their codes constantly, so this must not flood the log
-    expect(accessory.logWarn).toHaveBeenCalledTimes(1)
-    expect(accessory.logDebug).toHaveBeenCalledTimes(2)
-  })
-
-  it('still reports a genuinely different payload', () => {
-    const accessory = makeAccessory()
-
-    logUnknownData(accessory, { kind: 'scene', source: 'AWS', raw: 'abc' })
-    logUnknownData(accessory, { kind: 'scene', source: 'AWS', raw: 'xyz' })
-
-    expect(accessory.logWarn).toHaveBeenCalledTimes(2)
-  })
-
-  it('treats two different devices separately', () => {
-    const one = makeAccessory({ gvDeviceId: 'DEVICE:1' })
-    const two = makeAccessory({ gvDeviceId: 'DEVICE:2' })
-
-    logUnknownData(one, { kind: 'scene', source: 'AWS', raw: 'abc' })
-    logUnknownData(two, { kind: 'scene', source: 'AWS', raw: 'abc' })
-
-    expect(one.logWarn).toHaveBeenCalledTimes(1)
-    expect(two.logWarn).toHaveBeenCalledTimes(1)
-  })
-
-  it('leaves out fields the device has not told us', () => {
-    const accessory = makeAccessory({ firmware: undefined, hardware: undefined })
-    logUnknownData(accessory, { kind: 'scene', source: 'AWS', raw: 'abc' })
-
-    const payload = payloadOf(accessory)
-    expect(payload).not.toHaveProperty('firmware')
-    expect(payload).not.toHaveProperty('hardware')
-    expect(payload.model).toBe('H6102')
-  })
-
-  it('records an object payload rather than dropping it', () => {
-    const accessory = makeAccessory()
-    logUnknownData(accessory, { kind: 'payload', source: 'LAN', raw: { foo: 'bar' } })
-
-    expect(payloadOf(accessory).raw).toBe('{"foo":"bar"}')
-  })
-
-  it('copes with a payload that is not base64', () => {
-    const accessory = makeAccessory()
-
-    expect(() => logUnknownData(accessory, {
-      kind: 'scene',
-      source: 'AWS',
-      raw: 'not base64 !!',
-    })).not.toThrow()
-    expect(accessory.logWarn).toHaveBeenCalledTimes(1)
-  })
-
-  it('says nothing when there is no accessory', () => {
-    expect(() => logUnknownData(undefined, { kind: 'scene', raw: 'abc' })).not.toThrow()
-  })
-
-  describe('a control that is not worked out yet', () => {
-    it('names the control and what was asked for', () => {
-      const accessory = makeAccessory()
-      reportUnsupportedControl(accessory, { control: 'fan speed', value: 50 })
-
-      const line = reported(accessory)
-      expect(line).toContain('fan speed')
-      expect(line).toContain('did not happen')
-
-      const payload = JSON.parse(line.slice(line.indexOf('{')))
-      expect(payload.model).toBe('H6102')
-      expect(payload.firmware).toBe('1.03.01')
-      expect(payload.requested).toBe(50)
-    })
-
-    it('asks the user to report it', () => {
-      const accessory = makeAccessory()
-      reportUnsupportedControl(accessory, { control: 'fan speed', value: 1 })
-
-      expect(reported(accessory)).toContain('please report this line')
-    })
-
-    it('warns once per control, then keeps quiet', () => {
-      const accessory = makeAccessory()
-
-      reportUnsupportedControl(accessory, { control: 'fan speed', value: 25 })
-      reportUnsupportedControl(accessory, { control: 'fan speed', value: 50 })
-
-      expect(accessory.logWarn).toHaveBeenCalledTimes(1)
-      expect(accessory.logDebug).toHaveBeenCalledTimes(1)
-    })
-
-    it('still reports a different control on the same device', () => {
-      const accessory = makeAccessory()
-
-      reportUnsupportedControl(accessory, { control: 'fan speed', value: 25 })
-      reportUnsupportedControl(accessory, { control: 'ice size', value: 2 })
-
-      expect(accessory.logWarn).toHaveBeenCalledTimes(2)
-    })
-
-    it('does not throw when there is no accessory', () => {
-      expect(() => reportUnsupportedControl(undefined, { control: 'fan speed' })).not.toThrow()
-    })
-  })
-
-  describe('isFirstReport', () => {
-    it('is true once and false after', () => {
-      expect(isFirstReport('a')).toBe(true)
-      expect(isFirstReport('a')).toBe(false)
-      expect(isFirstReport('b')).toBe(true)
-    })
-  })
-})