qingping-cgd1 0.1.0__tar.gz

qingping_cgd1-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - run: uv sync --group dev
+      - run: uv run ruff check --output-format=github .
+      - run: uv run ruff format --check .
+
+  typecheck:
+    name: mypy --strict
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - run: uv sync --group dev --group test
+      - run: uv run mypy qingping_cgd1
+
+  test:
+    name: pytest (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - run: uv sync --group test
+      - run: >-
+          uv run --no-sync pytest
+          --cov=qingping_cgd1
+          --cov-branch
+          --cov-report=term-missing
+          --cov-report=xml
+      - run: >-
+          uv run --no-sync coverage report
+          --include="*/codec.py,*/models.py,*/const.py" --fail-under=100
+
+  zizmor:
+    name: zizmor
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - run: uvx zizmor@1.25.2 --persona=pedantic .github/workflows

qingping_cgd1-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: false
+      - run: uv build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC token for trusted publishing; no stored secret
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

qingping_cgd1-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Scratch
+.superpowers/

qingping_cgd1-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Coleman
+
+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.

qingping_cgd1-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: qingping-cgd1
+Version: 0.1.0
+Summary: Pure-Python BLE library for the Qingping CGD1 alarm clock
+Project-URL: Homepage, https://github.com/rjocoleman/qingping-cgd1
+Project-URL: Source, https://github.com/rjocoleman/qingping-cgd1
+Author: Robert Coleman
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alarm-clock,ble,bluetooth,cgd1,qingping
+Requires-Python: >=3.14.2
+Requires-Dist: bleak-retry-connector>=3.5
+Requires-Dist: bleak>=0.22
+Description-Content-Type: text/markdown
+
+# qingping-cgd1
+
+Local BLE control for the Qingping CGD1 "Dove" alarm clock. Pure Python, no
+cloud. Not affiliated with Qingping.
+
+## Install
+
+```
+pip install qingping-cgd1
+```
+
+Requires Python 3.14.2+. Depends only on `bleak` and `bleak-retry-connector`.
+
+## Passive sensor reading
+
+Temperature, humidity, and battery ride in the BLE advertisement, so you can
+read them without connecting to the device:
+
+```python
+from qingping_cgd1 import parse_advertisement
+
+reading = parse_advertisement(service_data)  # the 0xfdcd service-data bytes
+if reading is not None:
+    print(reading.temperature, reading.humidity, reading.battery)
+```
+
+## Active control
+
+Everything else - settings, alarms, time sync - needs a connection,
+authenticated with a `bleak` `BLEDevice`:
+
+```python
+from qingping_cgd1 import Alarm, QingpingCGD1Client, Weekday
+
+async with QingpingCGD1Client(ble_device) as client:
+    settings = await client.read_settings()
+    await client.write_settings(settings)
+
+    alarms = await client.read_alarms()
+    await client.write_alarm(0, Alarm(
+        enabled=True,
+        hour=7,
+        minute=30,
+        days=frozenset({Weekday.MONDAY, Weekday.TUESDAY}),
+        snooze=True,
+    ))
+    await client.delete_alarm(1)
+
+    await client.sync_time()
+    info = await client.read_firmware()
+```
+
+`QingpingCGD1Client` also has explicit `connect()`/`disconnect()` methods if
+you'd rather not use it as a context manager. It authenticates with a
+16-byte token (overridable via the `token` argument, default
+`DEFAULT_AUTH_TOKEN`), retries a timed-out command once after a reconnect,
+and disconnects automatically after `disconnect_delay` seconds of
+inactivity (default 120s).
+
+### Working out the next alarm
+
+`next_alarm` takes the list from `read_alarms()` and a reference time, and
+returns the soonest upcoming fire time (or `None` if nothing is enabled):
+
+```python
+from datetime import datetime
+
+from qingping_cgd1 import next_alarm
+
+upcoming = next_alarm(alarms, datetime.now())
+```
+
+## Protocol notes
+
+This library is reverse-engineered, not an official SDK. The protocol was
+mapped mainly by [MrBoombastic/clOwOck](https://github.com/MrBoombastic/clOwOck),
+an Android app for the CGD1; this is a Python port of that work. A few things
+worth knowing before you rely on it:
+
+- There are no checksums on the wire. Frames are fixed-layout and unvalidated
+  by the device beyond their length.
+- The 16-byte auth token is a per-device pairing secret, not a universal
+  key. A clock that's already paired (for example, one that's been used
+  with the official Qingping+ app) will reject the default token: the
+  device answers auth step 2 with `04 ff 02 00 01` (fail). You need to
+  unbind/reset the clock first - long-press its button until the
+  Bluetooth icon flashes, or remove it in the Qingping+ app - after which
+  it binds to the first token it's presented with. This library presents
+  its default token, and from then on that token authenticates every
+  time. The token is injectable via the `token` argument if you'd rather
+  manage pairing secrets yourself.
+- The `0xfdcd` advertisement layout (`model | mac | temperature | humidity |
+  battery`) is confirmed from a real CGD1 capture (firmware 1.0.1_0130):
+  decoding it gave 20.0 C / 51.7% / 80%, matching the device's own
+  display. There are still two unknown/reserved byte pairs in the frame
+  whose meaning isn't established.
+
+## Scope
+
+Covers passive sensor reading from advertisements, settings read/write,
+all 16 alarm slots, and time sync. Ringtone upload is not implemented.
+
+## How this was built
+
+Built largely with AI assistance (Claude) and tested against a real CGD1
+(firmware 1.0.1_0130). Tested and working, but a spare-time project - no
+warranty, no support promises.
+
+## Licence
+
+MIT.

qingping_cgd1-0.1.0/README.md

@@ -0,0 +1,111 @@
+# qingping-cgd1
+
+Local BLE control for the Qingping CGD1 "Dove" alarm clock. Pure Python, no
+cloud. Not affiliated with Qingping.
+
+## Install
+
+```
+pip install qingping-cgd1
+```
+
+Requires Python 3.14.2+. Depends only on `bleak` and `bleak-retry-connector`.
+
+## Passive sensor reading
+
+Temperature, humidity, and battery ride in the BLE advertisement, so you can
+read them without connecting to the device:
+
+```python
+from qingping_cgd1 import parse_advertisement
+
+reading = parse_advertisement(service_data)  # the 0xfdcd service-data bytes
+if reading is not None:
+    print(reading.temperature, reading.humidity, reading.battery)
+```
+
+## Active control
+
+Everything else - settings, alarms, time sync - needs a connection,
+authenticated with a `bleak` `BLEDevice`:
+
+```python
+from qingping_cgd1 import Alarm, QingpingCGD1Client, Weekday
+
+async with QingpingCGD1Client(ble_device) as client:
+    settings = await client.read_settings()
+    await client.write_settings(settings)
+
+    alarms = await client.read_alarms()
+    await client.write_alarm(0, Alarm(
+        enabled=True,
+        hour=7,
+        minute=30,
+        days=frozenset({Weekday.MONDAY, Weekday.TUESDAY}),
+        snooze=True,
+    ))
+    await client.delete_alarm(1)
+
+    await client.sync_time()
+    info = await client.read_firmware()
+```
+
+`QingpingCGD1Client` also has explicit `connect()`/`disconnect()` methods if
+you'd rather not use it as a context manager. It authenticates with a
+16-byte token (overridable via the `token` argument, default
+`DEFAULT_AUTH_TOKEN`), retries a timed-out command once after a reconnect,
+and disconnects automatically after `disconnect_delay` seconds of
+inactivity (default 120s).
+
+### Working out the next alarm
+
+`next_alarm` takes the list from `read_alarms()` and a reference time, and
+returns the soonest upcoming fire time (or `None` if nothing is enabled):
+
+```python
+from datetime import datetime
+
+from qingping_cgd1 import next_alarm
+
+upcoming = next_alarm(alarms, datetime.now())
+```
+
+## Protocol notes
+
+This library is reverse-engineered, not an official SDK. The protocol was
+mapped mainly by [MrBoombastic/clOwOck](https://github.com/MrBoombastic/clOwOck),
+an Android app for the CGD1; this is a Python port of that work. A few things
+worth knowing before you rely on it:
+
+- There are no checksums on the wire. Frames are fixed-layout and unvalidated
+  by the device beyond their length.
+- The 16-byte auth token is a per-device pairing secret, not a universal
+  key. A clock that's already paired (for example, one that's been used
+  with the official Qingping+ app) will reject the default token: the
+  device answers auth step 2 with `04 ff 02 00 01` (fail). You need to
+  unbind/reset the clock first - long-press its button until the
+  Bluetooth icon flashes, or remove it in the Qingping+ app - after which
+  it binds to the first token it's presented with. This library presents
+  its default token, and from then on that token authenticates every
+  time. The token is injectable via the `token` argument if you'd rather
+  manage pairing secrets yourself.
+- The `0xfdcd` advertisement layout (`model | mac | temperature | humidity |
+  battery`) is confirmed from a real CGD1 capture (firmware 1.0.1_0130):
+  decoding it gave 20.0 C / 51.7% / 80%, matching the device's own
+  display. There are still two unknown/reserved byte pairs in the frame
+  whose meaning isn't established.
+
+## Scope
+
+Covers passive sensor reading from advertisements, settings read/write,
+all 16 alarm slots, and time sync. Ringtone upload is not implemented.
+
+## How this was built
+
+Built largely with AI assistance (Claude) and tested against a real CGD1
+(firmware 1.0.1_0130). Tested and working, but a spare-time project - no
+warranty, no support promises.
+
+## Licence
+
+MIT.

qingping_cgd1-0.1.0/lefthook.yml

@@ -0,0 +1,21 @@
+pre-commit:
+  parallel: true
+  commands:
+    ruff-check:
+      glob: "*.py"
+      run: uv run ruff check --force-exclude {staged_files}
+      stage_fixed: true
+    ruff-format:
+      glob: "*.py"
+      run: uv run ruff format --check --force-exclude {staged_files}
+    mypy:
+      glob: "*.py"
+      run: uv run mypy qingping_cgd1
+    zizmor:
+      glob: ".github/workflows/*.{yml,yaml}"
+      run: uvx zizmor@1.25.2 {staged_files}
+
+pre-push:
+  commands:
+    pytest:
+      run: uv run pytest

qingping_cgd1-0.1.0/mise.toml

@@ -0,0 +1,11 @@
+[tools]
+python = "3.14"
+uv = "latest"
+lefthook = "2.1.9"
+zizmor = "1.25.2"
+
+[settings]
+python.uv_venv_auto = "create|source"
+
+[env]
+UV_PYTHON = { value = "{{ tools.python.path }}", tools = true }

qingping_cgd1-0.1.0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "qingping-cgd1"
+version = "0.1.0"
+description = "Pure-Python BLE library for the Qingping CGD1 alarm clock"
+readme = "README.md"
+requires-python = ">=3.14.2"
+license = "MIT"
+authors = [{ name = "Robert Coleman" }]
+keywords = ["bluetooth", "ble", "qingping", "cgd1", "alarm-clock"]
+dependencies = [
+  "bleak>=0.22",
+  "bleak-retry-connector>=3.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/rjocoleman/qingping-cgd1"
+Source = "https://github.com/rjocoleman/qingping-cgd1"
+
+[dependency-groups]
+dev = [
+  "ruff>=0.15",
+  "mypy>=2.1",
+]
+test = [
+  "pytest>=8.3",
+  "pytest-asyncio>=0.25",
+  "pytest-cov>=6.0",
+  "freezegun>=1.5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["qingping_cgd1"]
+
+[tool.ruff]
+required-version = ">=0.14"
+target-version = "py314"
+line-length = 88
+src = ["qingping_cgd1", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "A", "ASYNC", "B", "BLE", "C4", "C90", "D", "DTZ", "E", "EM", "EXE", "F",
+  "FA", "FLY", "FURB", "G", "I", "ICN", "INP", "ISC", "LOG", "N", "PERF",
+  "PGH", "PIE", "PL", "PT", "PTH", "RET", "RSE", "RUF", "S", "SIM", "SLF",
+  "SLOT", "T20", "TC", "TID", "TRY", "UP", "W",
+]
+ignore = [
+  "D203",   # incompatible with D211
+  "D213",   # incompatible with D212
+  "E501",   # the formatter owns line width
+  "ISC001", # conflicts with the formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+  "D",       # tests document themselves through their names
+  "S101",    # asserts are the point of tests
+  "PLR2004", # magic values are fine in tests
+  "SLF001",  # tests reach into internals
+]
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = true
+combine-as-imports = true
+known-first-party = ["qingping_cgd1"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 12
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+warn_unreachable = true
+enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
+follow_imports = "normal"
+local_partial_types = true
+no_implicit_reexport = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+asyncio_mode = "auto"
+addopts = "-ra --strict-markers --strict-config"
+
+[tool.coverage.run]
+branch = true
+source = ["qingping_cgd1"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = [
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+  "@overload",
+]

qingping_cgd1-0.1.0/qingping_cgd1/__init__.py

@@ -0,0 +1,56 @@
+"""Pure-Python BLE library for the Qingping CGD1 alarm clock."""
+
+from __future__ import annotations
+
+from .client import QingpingCGD1Client
+from .codec import (
+    decode_alarm,
+    decode_settings,
+    encode_alarm,
+    encode_settings,
+    encode_time,
+    next_alarm,
+    parse_advertisement,
+    parse_connected_sensor,
+)
+from .const import ALARM_SLOT_COUNT, DEFAULT_AUTH_TOKEN
+from .exceptions import (
+    AuthError,
+    CommandError,
+    ConnectionError,  # noqa: A004 - deliberate re-export, see exceptions.py
+    QingpingError,
+)
+from .models import (
+    Alarm,
+    DeviceInfo,
+    DeviceSettings,
+    Language,
+    SensorData,
+    Weekday,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ALARM_SLOT_COUNT",
+    "DEFAULT_AUTH_TOKEN",
+    "Alarm",
+    "AuthError",
+    "CommandError",
+    "ConnectionError",
+    "DeviceInfo",
+    "DeviceSettings",
+    "Language",
+    "QingpingCGD1Client",
+    "QingpingError",
+    "SensorData",
+    "Weekday",
+    "decode_alarm",
+    "decode_settings",
+    "encode_alarm",
+    "encode_settings",
+    "encode_time",
+    "next_alarm",
+    "parse_advertisement",
+    "parse_connected_sensor",
+]