govee-ble-local 1.2.0__tar.gz

govee_ble_local-1.2.0/CHANGELOG.md

@@ -0,0 +1,294 @@
+# Changelog
+
+Notable changes to `govee-ble-local`. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); the project follows
+[Semantic Versioning](https://semver.org/) and is versioned in `pyproject.toml`. Entries are grouped
+**Added / Changed / Fixed / Spec** (Spec = the Kaitai `spec/*.ksy` + `spec/devices.yaml` protocol
+model, from which the shipped readers are generated).
+
+## [Unreleased]
+
+## [1.2.0] — 2026-10-12
+
+First release published to PyPI. `1.1.0` was bumped on a development branch but never tagged or
+released, so its changes ship here too (see the `1.1.0` entry below).
+
+Hardening release candidate: input validation, connection/lifecycle reliability, secret handling
+and packaging. Behaviour changes that can affect callers are listed under **Behaviour changes**.
+
+### Added
+- `GoveeBleInvalidValue` (a `ValueError` subclass, also a `GoveeBleError`): raised for bad setter
+  input: colour channels, kelvin outside the device's `min_kelvin`/`max_kelvin`, segment/zone
+  indices and masks, scene payloads, secret length. Builders and AES/RC4 key lengths are validated too.
+- `Device.connect()`, an `idle_disconnect` argument on `Device`/`create_device`, and
+  `Device.scene_upload_frames(scene)` (the planned upload frames, or `None`).
+- `__version__` and more public exports: `Encryption`, `Scene`, `StateCallback`, `profile_for`,
+  `GoveeBleInvalidValue`.
+- `app_version` argument on the cloud account (overrides the `appVersion` request header).
+- `govee-ble-analyze --from-frames-log` input is validated (malformed lines are skipped, reported
+  and counted).
+- Dev tooling: `dev` and `audit` extras, `scripts/audit.sh`, a `[tool.vulture]` config, an
+  independent AES reference test (`pycryptodome`, test-only), ruff/mypy-strict/bandit/pip-audit
+  gates in `scripts/check.sh` and CI, and a tag-triggered PyPI trusted-publishing workflow.
+
+### Changed
+- `kaitaistruct>=0.11` (was unpinned below); SPDX `license = "MIT"` metadata; classifiers, `Issues`
+  URL and a markdown `readme` content type for PyPI.
+- The sdist no longer bundles `tests/`; it carries only `src/`, `pyproject.toml`, `README.md`,
+  `LICENSE` and `CHANGELOG.md`.
+- Profile fields are `Literal`-typed and validated at construction.
+- Segment merge / scene planning moved into `wire/` and `scenes/`; `Device` uses public
+  `scene_upload_frames`; the private scene alias was removed.
+- CI: SHA-pinned actions with minimal permissions, Python 3.11-3.13 matrix, lowest-dependency job;
+  optional test dependencies fail instead of skipping when `CI` is set.
+
+### Fixed
+- A disconnect racing an in-flight acknowledgement no longer leaves the write waiting or raises a
+  non-library error; a link lost while the write lock is held raises a typed error.
+- A slow poll can no longer overwrite state set by a newer setter (mutation-sequence guard).
+- Relay power: power frames are acknowledged and the resulting state is applied; time sync is
+  best-effort.
+- Bar-switch devices (H6047): the read-modify-write of the two-bar frame is serialized; the other
+  bar's state is read before use.
+- Lifecycle leaks: client/link no longer leaked on handshake, device-info and disconnect error
+  paths; detached disconnects are bounded in time.
+- Plaintext receive queue (no decrypt with a stale session key); a queued frame arriving at the
+  deadline is not lost; the end-of-burst sentinel is never dropped.
+- Device-info link errors no longer fail `update()`; device info is retried.
+- Encryption fallback when the advertised mode is wrong; secret length is checked.
+- State callbacks no longer break the notify pump or each other (exceptions are logged).
+- Colour groups with an invalid index are skipped instead of producing negative segment indices;
+  V1 segment brightness stays `None`.
+- Cloud client: response shapes are validated (status checked before JSON parsing, token type
+  check); the owned session is closed when login fails; one malformed device secret no longer
+  fails the whole account.
+- Scene catalogs: SKUs are validated, malformed catalogs and bad base64 raise library errors, and
+  catalog writes by `tools/fetch_scenes.py` are atomic.
+- Hardware tools: SKU/path validation, argparse, btsnoop length caps, restore-in-`finally`;
+  `tools/decrypt_btsnoop.py`/`btsnoop_mtu_scan.py` mask the account secret.
+
+### Security
+- Frame-log files are created `0600`, written with `O_NOFOLLOW`, refused if not a regular file,
+  bounded (oldest records dropped when full) and flushed at interpreter exit; a dead writer is
+  revived. Docs now state that captures are sensitive (the session key is derivable from them).
+- Cloud responses are shape-validated; malformed device secrets are never echoed.
+- Secret masking in captures shares one implementation and recomputes the frame checksum.
+- CI runs `bandit` (Medium+) and `pip-audit`; the three accepted `cryptography` advisories are
+  documented (AES-ECB/ARC4 only; PKCS#7/X.509 unused).
+
+### Behaviour changes (may affect callers)
+- Bar-switch devices: `set_zone_power` raises when the other bar's state is unknown and cannot be
+  read, instead of assuming it is on.
+- `GoveeBleAuthError` is no longer retried.
+- `send(expect_ack=True)` rejects non-write frames.
+- Setters raise `GoveeBleInvalidValue` (still a `ValueError`) for invalid input, including kelvin
+  outside the profile's `min_kelvin`/`max_kelvin`. (Brightness percent is still clamped to 1..100.)
+- `Capability` and `Encryption` are `StrEnum`: `str(member)` now returns the value
+  (e.g. `"power"`), not `"Capability.POWER"`.
+- `load_scenes` returns copies (mutating the result does not affect the cache) and raises library
+  errors for malformed catalogs.
+- Cloud `get_devices` returns `secret=None` and logs a warning for a malformed secret rather than
+  failing.
+
+## [1.1.0] — 2026-10-12
+
+Reliability overhaul driven by five days of live frame captures (11 devices, 2 ESPHome proxies +
+a local adapter) and validated live on the same hardware: steady-state polls went from ~7.7 s
+with a 5 s stall (H60A6) and ~40 % failures to 1.5–4.5 s with no failures.
+
+### Fixed
+- **Secret leaked through `wire=` in frame captures.** Only the `plain=` field of the `33 b2` / `aa b1` secret frames was masked; on a plaintext link `wire=` is the same bytes, and on an encrypted link it is decryptable from the captured handshake plus the public PSK. Both fields (and the bad-checksum debug line) are now masked.
+- `set_segment_brightness` raised a bare `ValueError` on colour schemes without per-segment
+  brightness (H61A8); it now raises `GoveeBleNotSupported`, like `set_segment_color_temp`.
+- **Handshake raced the device.** The device delivers its `e7 01` reply twice and re-sends the
+  `e7 02` echo ~1 s later. The duplicate step-1 reply was consumed as the step-2 "ack", so the
+  first query fired while the confirm was still in flight; ~90 % of H60A6 sessions then lost the
+  `0xFF` terminator of their first status burst (5 s stall + retry on every poll). Replies are
+  now matched by content, the real confirm is awaited, and late retransmits are dropped.
+- Frames failing the XOR checksum are dropped at the notify pump (they were the source of the
+  intermittent "unknown proType 0x67/0x7f/0xa5" warnings: handshake echoes decrypted with the
+  session key that happened to pass the checksum).
+- A link that stops acknowledging writes (half-dead while bleak still reports "connected") is
+  torn down and the write retried once on a fresh link, instead of failing the command.
+- A disconnect wakes pending waits immediately; a late disconnect callback from a superseded
+  client no longer clears the current one.
+- The idle-disconnect timer can no longer fire after newer activity (it used to disconnect
+  right after a command and force a reconnect); its task is now held so it can't be GC'd.
+- `establish_connection` gets `ble_device_callback`, so retries use the freshest proxy path.
+- Every public operation has a hard deadline (`OPERATION_TIMEOUT`) and raises only
+  `GoveeBleError` subclasses (bleak/asyncio errors no longer leak out of `send`/`query`).
+- 0xAC reassembly joins only the contiguous chunk prefix (a gap used to splice later chunks at
+  the wrong offset and decode garbage as real state) and decodes a truncated burst up to its last
+  whole TLV, so a lost tail yields partial-but-true state without a retry; queries end on a short
+  idle gap instead of the full timeout when a terminator is lost.
+- 0x0d bulbs (H6006/H6008/H6052): the mode report is `[r, g, b, kelvin u2be]`; white + kelvin is
+  colour-temperature mode. H6052's "mechanism C" decoded it as RGB-only (reporting white instead
+  of 2700 K, live capture `aa 05 0d ff ff ff 0a 8c`) and issued a duplicate mode query; all three
+  bulbs now read colour/CCT back from the report they already send.
+- Polled devices always re-read power (previously skipped once a device was off, so a light
+  turned on externally was never noticed).
+- H6047: changing one bar no longer assumes the other bar is ON when its state is unknown (it
+  turned the other bar on); the bar state is read back (`aa 36`) and polled.
+- Advertised on/off is ignored for 15 s after a command/read (stale broadcasts flipped state).
+- Brightness is never sent as 0; the reported-brightness scale is an explicit profile field
+  (`brightness_max`) instead of a `>100 means 0-255` guess.
+- Scene uploads are paced instead of blasted (dropped frames over proxies).
+- Account-lock secrets are masked in frame captures (logs/diagnostics).
+- `FrameLog` file writes moved off the event loop.
+- Cloud client: request timeouts, the documented-but-missing re-login on 401, no response bodies
+  in error messages, no forced login when a token is supplied.
+
+### Added
+- `Device.turn_on(brightness=, rgb=, kelvin=, power=)` / `turn_off()` and
+  `GoveeConnection.send_many()`: multi-attribute changes go out as one batched, ack-verified
+  operation on one connection. Whole-fixture power is always one frame: H60A6 uses the global
+  `33 01` switch (live-verified to drive both zones: off clears them, on lights both even when
+  each was off; previously one `33 30` frame per zone), H6047 the combined `33 36` bar frame.
+- `GoveeBleAuthError` is raised when a device rejects its secret key.
+- `Device.encryption` (the negotiated channel mode); colour temperature read back from the mode
+  report; segment writes update `state.segments`.
+- `tools/power_semantics_probe.py`: hardware experiment for global vs. zone power.
+- Fake-peripheral test harness (`tests/fake_ble.py`) reproducing the captured failure modes;
+  release workflow publishing to PyPI via trusted publishing.
+
+### Removed
+- Dead code: `ble/frame.py`, duplicate `checksum_ok`, unused `CONNECT_TIMEOUT`.
+
+## [1.0.3] — 2026-07-12
+
+Field-tested and confirmed live on H60A6 before merge (see PR discussion): a truncated 9-of-11-chunk
+burst recovered fully on retry with no warning; an H6047/H6641-style zero-chunk case correctly
+logged `state left stale` with chunk indices after the retry, rather than papering over it.
+
+### Fixed
+- `Device._read_status()` (the `0xAC` status read-back for `readback="status"` devices, e.g. H60A6)
+  now **retries once** on an empty parse before leaving state stale. A dropped BLE notification
+  mid-burst yields a truncated or empty reassembled buffer — reported in the field as
+  `status reply did not parse (0 bytes): ... requested 1 bytes, but only 0 bytes available` and
+  `status reply did not parse (148 bytes): ... requested 17 bytes, but only 12 bytes available`
+  (`wire/reassemble.py` DEBUG log). This was already non-fatal (fields are applied conditionally,
+  so a failed parse can't erase known-good state) and already surfaced a WARNING
+  (`"... state left stale"`), but a single dropped notification cost a whole poll cycle; a fresh
+  query is independent and usually succeeds immediately. Both the retry-attempt DEBUG line and the
+  final WARNING now also report which `0xAC` chunk indices were actually received (e.g.
+  `0x00,0x01,0x02,0x04,0xff`, or `<none>`), to distinguish a dropped-mid-burst from a
+  completely-empty read on any future occurrence.
+
+## [1.0.2] — 2026-07-12
+
+### Fixed
+- **H6047/H6641's `1.0.1` colour read-back fix reused the wrong controller's decoder.** `1.0.1`
+  correctly identified that neither SKU dispatches the `0xAC` status burst, but wired their
+  per-segment colour read-back onto H61A8's `mechanism_b` (`BulbGroupColorV2`) decoder —
+  a *different, unrelated controller* that only happens to share the `0xA5` wire opcode with
+  the one H6047/H6641 actually use (`Controller4ColorInfoByGroup`, confirmed via a full re-read
+  of `devices.yaml`: *"SAME PARSER ... but TWO different TRANSPORTS"*, explicitly distinct from
+  H61A8's separately-listed `BulbGroupColor`/mechanism-B). The two decoders disagree on group
+  size (3 vs 4), so segment indices were silently misassigned. Caught by the test suite itself
+  before any further guessing — a second wrong per-batch value (5, conflating two unrelated
+  "5"s from two different code paths) was caught the same way and never shipped.
+- New `color_readback="mechanism_a_direct"` (`wire.parse.parse_direct_color_group`,
+  `Device._read_mechanism_a_direct`) correctly decodes `Controller4ColorInfoByGroup`'s per-group
+  reply — group size **4**, source-confirmed independently for both SKUs
+  (`devices.yaml`: *"4/group"* / *"4 records/group"*), not extrapolated from H61A8.
+- **H6641's group-count approximation is now resolved, not just documented**: a live `0x40`
+  IC-count read (`build.ic_count_query`, `wire.parse.parse_ic_count`, the already-modeled
+  `ic_segment_read` ksy type) returns the device's own precomputed group count directly —
+  no client-side ceil-division/divisor guess needed. New `DeviceProfile.color_readback_live_ic`
+  flag gates this per-SKU (H6641 only; H6047 keeps its static, source-confirmed piece count).
+- `Device._read_mechanism_b` is now H61A8-only again (its docstring no longer over-claims
+  sharing with H6047/H6641).
+
+## [1.0.1] — 2026-07-12
+
+### Fixed
+- **H6047 and H6641 never actually answer the `0xAC` status burst** — they were wrongly modeled
+  as mechanism-A (the same `0xAC → 0xA5` path as H60A6), which produced a deterministic
+  zero-frame read on real hardware (source-confirmed, not a wire/timing issue: `H6047`, goodsType
+  119, routes to `Compose4InfoBleIot`, `Support.isGoodsTypeH6047:177`; `H6641`, goodsType 247,
+  never reaches the `afterConnected` `0xAC` dispatch at all, `H61D3Support.f0(247)=false`). Both
+  read per-segment colour via **direct per-group requests** instead (`AA A5 <group>`,
+  `Controller4ColorInfoByGroup` — the same decode H61A8 already used as `mechanism_b`).
+  `DeviceProfile.readback` for both switches `"status"` → `"polled"` (power/brightness/scene via
+  `aa 01/04/05`); `color_readback="mechanism_b"` added for both, reusing the existing decoder.
+  New `DeviceProfile.color_readback_segments` field lets H6047's batch math use its true
+  read-back piece count (`getColorPieceSize`=12) instead of its write/addressable count (10),
+  which differ for this SKU.
+  **Two related approximations remain open (flagged in `profile.py`, not fixed by this change):**
+  H6641's true colour-group *count* is IC-driven (needs a live `0x40` read this library doesn't
+  perform yet — falls back to the write-mask width as an approximation), and its per-reply
+  *record count* assumption (3, matching H61A8's `BulbStringColorControllerV2`) is unconfirmed —
+  H6641 may use an unmodeled `V3` controller with a different count/layout. Neither SKU is yet
+  live-verified.
+
+### Spec
+- `devices.yaml` / `docs/GOVEE_BLE_GATT_PROTOCOL.md`: documented the H6047/H6641 `0xAC`
+  non-dispatch (source citations above) and their `per_segment_color_read` direct-request
+  transport; reconciled `H61D3Support.e()`'s divisor (`d ∈ {3,4}` → `d ∈ {3,4,5}`, H6641/247 = 5)
+  against the `ceil(IC/5)` group-count math.
+
+## [1.0.0] — 2026-07-11
+
+First public release. Prior `v1`/`v2`/`v3` were internal rewrite generations (never tagged or
+published); `1.0.0` is the initial Semantic-Versioning baseline, committing to the
+`govee_ble_local.__all__` public API. This release is the ground-up **v3-generation rewrite**: a
+data-driven `DeviceProfile` table + one capability-gated `Device` class over a spec-first `wire/`
+layer (build / parse / reassemble) and the shipped, ksy-generated readers. Clean break from the
+old `GoveeBleClient` API.
+
+### Added
+- Capability-driven `Device` + `create_device()` / `discover()` / `DeviceProfile` public API.
+- Colour temperature per zone/segment: `Device.set_zone_color_temp()` / `set_segment_color_temp()`
+  + `build.segment_color_temp()` (the 0x15 CCT frame's segment mask, previously all-segments only).
+- Read-back: plug relay power, H6047 segment colours (mechanism-A status), and device-info
+  (`serial` / `wifi_mac` / `firmware` / `hardware`), plus `DeviceState.ble_mac`.
+- `Device.set_gradual()` — the `0xA3` gradual/fade-on-BLE↔wifi-handoff flag (curated: H61A8;
+  read back into `DeviceState.gradual` on `update()`).
+- `Device.read_secret()` and `Device.ingest_advertisement()` restored (v2 parity).
+- Diagnostics: a coherent `govee_ble_local.*` log-level scheme, a `govee_ble_local.frames`
+  frame-tier logger for full-session capture (incl. over a Home Assistant Bluetooth proxy),
+  the `govee-ble-analyze` console script + a frames-log→JSONL converter, and `docs/DIAGNOSTICS.md`.
+- Live H60A6 tools: CCT choreography + a segment-map probe.
+
+### Changed
+- The reassembled `0xAC` status buffer is now parsed **entirely by the generated `StatusReply`
+  reader** — the hand TLV-walk (`walk_tlvs`), `_add_color_group`, and the MAC-anchor device-info
+  heuristic are all retired. Only the cross-frame de-chunk stays hand-done (Kaitai can't join
+  frames). The offline analyzer uses the same reader.
+- README + version brought to the v3 API; description now "Govee devices" (plugs included).
+- **Dependency hygiene:** `PyYAML` moved to the `test` extra — it isn't used at runtime (the device
+  table is hardcoded Python; `yaml` appears only in the test suite). Runtime deps are now
+  `bleak` / `bleak-retry-connector` / `cryptography` (HA defaults) + `kaitaistruct` (the one accepted
+  pure-Python exception). Added `[project.urls]`.
+- **Docs:** README install-from-source instructions (not yet on PyPI); a `pdoc` API reference
+  (`.[docs]` extra + `tools/gen_docs.sh`); a `CONTRIBUTING.md` (branching / commit / changelog /
+  release conventions); project conventions recorded for maintainers.
+
+### Fixed
+- H60A6 segment→zone map corrected (index 12 = main panel, 0–11 = background ring), making
+  per-zone colour/CCT genuinely independent — live-verified.
+- H60A6 `wifi_mac` / `hardware_version` read-back (regressed in the v3 clean break) restored,
+  now from the modeled `0x07` device-info TLV; zeroed `aa 07` replies no longer clobber real
+  values (`0.00.00` / all-zero → None).
+- `reassemble()` de-duplicates doubled status chunks (devices double-deliver notifications).
+
+### Spec
+- Modeled the reassembled `0xAC` nested TLV values (source-verified, `Compose4BaseInfoSingleRead`):
+  `status_tlv` switches `0x05→mode_status`, `0x07→device_info_read`, `0xA5→color_group_status`;
+  `status_reply` uses `repeat: until type==0` + `if: type != 0` to survive the trailing zero-pad.
+- Added `gradual_read` (0xA3) — now surfaced (`Device.set_gradual`) — and tag-grouped
+  `color_strip_write`, which is modeled but **not exposed**: it has no curated-SKU binding in
+  `devices.yaml` (needs source: which SKU uses `MultipleColorStripControllerV1` / comType 0x40, and
+  whether it complements or replaces `set_segment_rgb`).
+- Fixed a YAML-1.1 boolean id trap (`id: on` → parsed as `.true`); renamed to `state` / `on_flag`.
+- `devices.yaml`: H60A6 segment→zone map; H6641 colour records are 4-byte; mechanism-B/C read-back
+  and scene-dialect notes.
+- Adopted the parametric **Tier-C** grammar variants (`op15_color_typed`, `mode_color_0d_typed`;
+  joining `color_group_read`) so the ksy owns 100% of byte structure — the client passes one
+  discriminator and the branch runs inside the grammar. `devices.yaml` gained per-family
+  `client_profile` blocks (discriminators as data) + schema support. Readers regenerated; additive,
+  no runtime behaviour change.
+- `spec/` is now a self-documenting protocol package: added the canonical protocol docs
+  (`spec/docs/GOVEE_BLE_GATT_PROTOCOL.md`, `SCENE_UPLOAD_ENCODING.md`, `USING_THE_KSY.md`) and an
+  executable reference codec (`spec/govee_reference.py`) — the framing layer Kaitai can't express
+  (AES-ECB+RC4 decrypt, `0xAC` reassemble, XOR BCC) + dispatch wiring, with a self-test.

govee_ble_local-1.2.0/LICENSE

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

govee_ble_local-1.2.0/MANIFEST.in

@@ -0,0 +1,11 @@
+# sdist contents: the package, metadata and top-level docs only. No tests, tools, spec,
+# docs, scripts or CI config (those live in the git repo, not on PyPI).
+include LICENSE README.md CHANGELOG.md pyproject.toml
+graft src
+prune tests
+prune tools
+prune spec
+prune docs
+prune scripts
+prune .github
+global-exclude *.py[cod] __pycache__ .DS_Store

govee_ble_local-1.2.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: govee-ble-local
+Version: 1.2.0
+Summary: Local Bluetooth LE control of Govee devices — no cloud, no LAN API.
+Author: Brady Woods
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Brady-Woods/govee-ble-local
+Project-URL: Repository, https://github.com/Brady-Woods/govee-ble-local
+Project-URL: Changelog, https://github.com/Brady-Woods/govee-ble-local/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/Brady-Woods/govee-ble-local/issues
+Keywords: govee,bluetooth,ble,home-assistant,led,light
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.21
+Requires-Dist: bleak-retry-connector>=3.0.0
+Requires-Dist: cryptography<49,>=41.0.0
+Requires-Dist: kaitaistruct>=0.11
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: jsonschema>=4.0; extra == "test"
+Requires-Dist: PyYAML>=6.0; extra == "test"
+Requires-Dist: aiohttp>=3.9; extra == "test"
+Requires-Dist: pycryptodome; extra == "test"
+Provides-Extra: cloud
+Requires-Dist: aiohttp>=3.9; extra == "cloud"
+Provides-Extra: typing
+Requires-Dist: mypy; extra == "typing"
+Requires-Dist: types-PyYAML; extra == "typing"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: bandit; extra == "lint"
+Requires-Dist: pip-audit; extra == "lint"
+Provides-Extra: docs
+Requires-Dist: pdoc; extra == "docs"
+Provides-Extra: audit
+Requires-Dist: vulture; extra == "audit"
+Requires-Dist: radon; extra == "audit"
+Provides-Extra: dev
+Requires-Dist: govee-ble-local[audit,cloud,lint,test,typing]; extra == "dev"
+Requires-Dist: uv; extra == "dev"
+Dynamic: license-file
+
+# govee-ble-local
+
+**Local Bluetooth LE control of Govee devices — no cloud, no LAN API.**
+
+A standalone Python library implementing Govee's BLE control protocol (AES-ECB+RC4
+handshake, 20-byte command framing, multi-packet scene upload, and status read-back),
+derived from the decompiled Govee Home app and verified against real hardware. It's the
+protocol engine behind the
+[`hass-govee-ble-local`](https://github.com/Brady-Woods/hass-govee-ble-local)
+Home Assistant integration, but has no Home Assistant dependency and can be used on its own.
+
+> ⚠️ **Unofficial.** Not affiliated with or endorsed by Govee. Reverse-engineered from the
+> app + hardware; behavior may change with device firmware. Live-verified on the **H60A6**
+> (Ceiling Light Pro); the other curated SKUs are modelled from the app and are not all
+> hardware-verified (see the profile notes).
+
+## Install
+
+Not on PyPI yet — install from source:
+
+```bash
+pip install "git+https://github.com/Brady-Woods/govee-ble-local.git"
+# or, from a clone (editable):
+git clone https://github.com/Brady-Woods/govee-ble-local.git
+cd govee-ble-local && pip install -e .
+# optional Govee cloud-account helpers (pulls in aiohttp):
+pip install 'govee-ble-local[cloud]'
+```
+
+Requires Python 3.11+. Runtime dependencies are deliberately minimal and Home-Assistant-friendly:
+`bleak`, `bleak-retry-connector`, `cryptography` (all shipped with HA), plus `kaitaistruct` (a
+pure-Python, stdlib-only wire-parser runtime). Dev extras: `.[dev]` (everything a contributor needs), or individually `.[test]`, `.[typing]`,
+`.[lint]`, `.[audit]`, `.[docs]`.
+
+## Quick start
+
+```python
+import asyncio
+from govee_ble_local import create_device, discover
+
+async def main():
+    # Active-scan for supported Govee devices (strongest advertisement per address).
+    devices = await discover(timeout=8.0)
+    found = next(d for d in devices if d.sku == "H60A6")
+
+    dev = create_device(found.ble_device, found.sku)
+
+    await dev.turn_on()
+    await dev.set_brightness(60)             # percent
+    await dev.set_rgb((255, 0, 0))
+    await dev.set_zone_power("background", False)
+
+    state = await dev.update()               # read-back into dev.state
+    print(state.is_on, state.brightness, state.rgb_color, state.segments)
+
+    await dev.stop()
+
+asyncio.run(main())
+```
+
+## API
+
+The library follows Home-Assistant BLE-library conventions: identify a device from its
+advertisement, build a capability-driven `Device`, then drive it.
+
+- **`discover(timeout=10.0, *, supported_only=True)`** — active-scan → `list[DiscoveredDevice]`
+  (`.ble_device`, `.advertisement`, `.sku`, `.rssi`, `.supported`). `supported(name, mfg)` and
+  `match(ble_device, adv)` are the passive-matcher hooks for a HA-style scanner.
+- **`create_device(ble_device, sku, advertisement_data=None, *, secret=None, frame_log=None)`**
+  — construct a `Device` for the SKU (raises `GoveeBleNotSupported` if uncurated).
+  `is_supported_sku(sku)` / `supported_skus()` / `device_profile_for(sku)` query the table.
+- **`Device`** — one capability-gated class (behaviour comes from its `DeviceProfile`, not
+  subclasses). Commands are ACK-confirmed on the wire:
+  `turn_on` / `turn_off` / `set_power`, `set_brightness`, `set_rgb`, `set_color_temp`,
+  `set_segment_rgb` / `set_segment_brightness` / `set_segment_color_temp`,
+  `set_zone_power` / `set_zone_rgb` / `set_zone_color_temp`,
+  `set_scene` / `set_scene_by_name`, and `update()` (read-back). Introspection:
+  `capabilities`, `zones`, `min_kelvin` / `max_kelvin`, `scene_names`, `state`,
+  `register_callback`. Methods for unsupported capabilities raise `GoveeBleNotSupported`.
+- **`DeviceState`** — parsed state: `is_on`, `brightness` (0–100), `rgb_color`,
+  `color_temp_kelvin`, `segments` (`list[Segment]`), `zone_power`, `scene_code`, plus
+  device-info (`serial_number`, `wifi_mac`, `hardware_version`, `firmware_version`, `ble_mac`).
+- **`Capability`** — `POWER`, `BRIGHTNESS`, `RGB`, `COLOR_TEMP`, `SEGMENTS`, `SCENES`.
+
+Curated SKUs: **H60A6**, **H6047**, **H61A8**, **H6006/H6008**, **H6052**, **H6641**, and the
+plug family (**H5080/H5082/H5083/H5085/H5089/H5160/H5161**). Segment-colour read-back and some
+scene dialects on the non-H60A6 SKUs are source-modelled and not yet hardware-verified.
+
+The full API reference is generated from the docstrings with [`pdoc`](https://pdoc.dev)
+(`pip install '.[docs]' && bash tools/gen_docs.sh` → `docs/api/`); `govee_ble_local.__all__` is the
+public contract.
+
+## Security notes
+
+The Govee BLE protocol itself has well-known limits that this library cannot fix:
+
+- Its encryption uses a public pre-shared key, AES-ECB for the handshake and an RC4 stream for
+  traffic, and integrity is only an XOR checksum. Anyone within radio range can drive an
+  encrypted device.
+- Captures made with `GOVEE_FRAME_LOG` contain wire frames from which the session key can be
+  derived. Treat them as sensitive and do not post them publicly. Frame-log files are created
+  with owner-only permissions.
+
+## Diagnostics & session capture
+
+The library logs under the `govee_ble_local.*` hierarchy and can capture a full protocol
+session (over a local adapter or a Home Assistant Bluetooth proxy) for analysis. Enable the
+flow trace, or the per-frame firehose, and decode a capture with the bundled
+`govee-ble-analyze` CLI. See [`docs/DIAGNOSTICS.md`](docs/DIAGNOSTICS.md).
+
+## Protocol
+
+The wire protocol is specified as Kaitai Struct definitions — [`spec/govee_ble.ksy`](spec/govee_ble.ksy)
+(command/reply frames) and [`spec/govee_adv.ksy`](spec/govee_adv.ksy) (advertisements) — with the
+per-device table in [`spec/devices.yaml`](spec/devices.yaml). The runtime readers under
+`govee_ble_local/_generated/` are generated from those (source of truth: the decompiled Govee app).
+
+## Contributing & versioning
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, branching, commit, and release
+conventions. Changes are tracked in [`CHANGELOG.md`](CHANGELOG.md); the project follows
+[Semantic Versioning](https://semver.org/). Live hardware tests run against the curated SKUs above.
+
+## License
+
+[MIT](LICENSE) © Brady Woods

govee_ble_local-1.2.0/README.md

@@ -0,0 +1,126 @@
+# govee-ble-local
+
+**Local Bluetooth LE control of Govee devices — no cloud, no LAN API.**
+
+A standalone Python library implementing Govee's BLE control protocol (AES-ECB+RC4
+handshake, 20-byte command framing, multi-packet scene upload, and status read-back),
+derived from the decompiled Govee Home app and verified against real hardware. It's the
+protocol engine behind the
+[`hass-govee-ble-local`](https://github.com/Brady-Woods/hass-govee-ble-local)
+Home Assistant integration, but has no Home Assistant dependency and can be used on its own.
+
+> ⚠️ **Unofficial.** Not affiliated with or endorsed by Govee. Reverse-engineered from the
+> app + hardware; behavior may change with device firmware. Live-verified on the **H60A6**
+> (Ceiling Light Pro); the other curated SKUs are modelled from the app and are not all
+> hardware-verified (see the profile notes).
+
+## Install
+
+Not on PyPI yet — install from source:
+
+```bash
+pip install "git+https://github.com/Brady-Woods/govee-ble-local.git"
+# or, from a clone (editable):
+git clone https://github.com/Brady-Woods/govee-ble-local.git
+cd govee-ble-local && pip install -e .
+# optional Govee cloud-account helpers (pulls in aiohttp):
+pip install 'govee-ble-local[cloud]'
+```
+
+Requires Python 3.11+. Runtime dependencies are deliberately minimal and Home-Assistant-friendly:
+`bleak`, `bleak-retry-connector`, `cryptography` (all shipped with HA), plus `kaitaistruct` (a
+pure-Python, stdlib-only wire-parser runtime). Dev extras: `.[dev]` (everything a contributor needs), or individually `.[test]`, `.[typing]`,
+`.[lint]`, `.[audit]`, `.[docs]`.
+
+## Quick start
+
+```python
+import asyncio
+from govee_ble_local import create_device, discover
+
+async def main():
+    # Active-scan for supported Govee devices (strongest advertisement per address).
+    devices = await discover(timeout=8.0)
+    found = next(d for d in devices if d.sku == "H60A6")
+
+    dev = create_device(found.ble_device, found.sku)
+
+    await dev.turn_on()
+    await dev.set_brightness(60)             # percent
+    await dev.set_rgb((255, 0, 0))
+    await dev.set_zone_power("background", False)
+
+    state = await dev.update()               # read-back into dev.state
+    print(state.is_on, state.brightness, state.rgb_color, state.segments)
+
+    await dev.stop()
+
+asyncio.run(main())
+```
+
+## API
+
+The library follows Home-Assistant BLE-library conventions: identify a device from its
+advertisement, build a capability-driven `Device`, then drive it.
+
+- **`discover(timeout=10.0, *, supported_only=True)`** — active-scan → `list[DiscoveredDevice]`
+  (`.ble_device`, `.advertisement`, `.sku`, `.rssi`, `.supported`). `supported(name, mfg)` and
+  `match(ble_device, adv)` are the passive-matcher hooks for a HA-style scanner.
+- **`create_device(ble_device, sku, advertisement_data=None, *, secret=None, frame_log=None)`**
+  — construct a `Device` for the SKU (raises `GoveeBleNotSupported` if uncurated).
+  `is_supported_sku(sku)` / `supported_skus()` / `device_profile_for(sku)` query the table.
+- **`Device`** — one capability-gated class (behaviour comes from its `DeviceProfile`, not
+  subclasses). Commands are ACK-confirmed on the wire:
+  `turn_on` / `turn_off` / `set_power`, `set_brightness`, `set_rgb`, `set_color_temp`,
+  `set_segment_rgb` / `set_segment_brightness` / `set_segment_color_temp`,
+  `set_zone_power` / `set_zone_rgb` / `set_zone_color_temp`,
+  `set_scene` / `set_scene_by_name`, and `update()` (read-back). Introspection:
+  `capabilities`, `zones`, `min_kelvin` / `max_kelvin`, `scene_names`, `state`,
+  `register_callback`. Methods for unsupported capabilities raise `GoveeBleNotSupported`.
+- **`DeviceState`** — parsed state: `is_on`, `brightness` (0–100), `rgb_color`,
+  `color_temp_kelvin`, `segments` (`list[Segment]`), `zone_power`, `scene_code`, plus
+  device-info (`serial_number`, `wifi_mac`, `hardware_version`, `firmware_version`, `ble_mac`).
+- **`Capability`** — `POWER`, `BRIGHTNESS`, `RGB`, `COLOR_TEMP`, `SEGMENTS`, `SCENES`.
+
+Curated SKUs: **H60A6**, **H6047**, **H61A8**, **H6006/H6008**, **H6052**, **H6641**, and the
+plug family (**H5080/H5082/H5083/H5085/H5089/H5160/H5161**). Segment-colour read-back and some
+scene dialects on the non-H60A6 SKUs are source-modelled and not yet hardware-verified.
+
+The full API reference is generated from the docstrings with [`pdoc`](https://pdoc.dev)
+(`pip install '.[docs]' && bash tools/gen_docs.sh` → `docs/api/`); `govee_ble_local.__all__` is the
+public contract.
+
+## Security notes
+
+The Govee BLE protocol itself has well-known limits that this library cannot fix:
+
+- Its encryption uses a public pre-shared key, AES-ECB for the handshake and an RC4 stream for
+  traffic, and integrity is only an XOR checksum. Anyone within radio range can drive an
+  encrypted device.
+- Captures made with `GOVEE_FRAME_LOG` contain wire frames from which the session key can be
+  derived. Treat them as sensitive and do not post them publicly. Frame-log files are created
+  with owner-only permissions.
+
+## Diagnostics & session capture
+
+The library logs under the `govee_ble_local.*` hierarchy and can capture a full protocol
+session (over a local adapter or a Home Assistant Bluetooth proxy) for analysis. Enable the
+flow trace, or the per-frame firehose, and decode a capture with the bundled
+`govee-ble-analyze` CLI. See [`docs/DIAGNOSTICS.md`](docs/DIAGNOSTICS.md).
+
+## Protocol
+
+The wire protocol is specified as Kaitai Struct definitions — [`spec/govee_ble.ksy`](spec/govee_ble.ksy)
+(command/reply frames) and [`spec/govee_adv.ksy`](spec/govee_adv.ksy) (advertisements) — with the
+per-device table in [`spec/devices.yaml`](spec/devices.yaml). The runtime readers under
+`govee_ble_local/_generated/` are generated from those (source of truth: the decompiled Govee app).
+
+## Contributing & versioning
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, branching, commit, and release
+conventions. Changes are tracked in [`CHANGELOG.md`](CHANGELOG.md); the project follows
+[Semantic Versioning](https://semver.org/). Live hardware tests run against the curated SKUs above.
+
+## License
+
+[MIT](LICENSE) © Brady Woods