tuya-ble-sdk 0.1.1__tar.gz

tuya_ble_sdk-0.1.1/.github/dependabot.yml

@@ -0,0 +1,33 @@
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Sao_Paulo"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Sao_Paulo"
+    groups:
+      python-deps:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: "deps"
+      prefix-development: "deps-dev"
+      include: "scope"

tuya_ble_sdk-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    uses: roquerodrigo/workflows/.github/workflows/python-lint.yml@main
+
+  tests:
+    needs: lint
+    uses: roquerodrigo/workflows/.github/workflows/python-test.yml@main
+
+  update-pr-branch:
+    if: github.event_name == 'pull_request'
+    needs: [lint, tests]
+    permissions:
+      contents: write
+      pull-requests: write
+    uses: roquerodrigo/workflows/.github/workflows/update-pr-branch.yml@main

tuya_ble_sdk-0.1.1/.github/workflows/codeql.yml

@@ -0,0 +1,18 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "0 0 * * 0"
+
+permissions: {}
+
+jobs:
+  codeql:
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    uses: roquerodrigo/workflows/.github/workflows/codeql.yml@main

tuya_ble_sdk-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+# Three composable stages: release-please grooms the release pull request and
+# tags it, the lock is refreshed on the release branch so it lands carrying the
+# same version, and the tag is published to PyPI.
+#
+# The `workflow_run.event == 'push'` condition is what stops a pull request with
+# green CI from cutting a release.
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to republish to PyPI, for example v1.1.0. Skips release-please."
+        required: true
+        type: string
+
+permissions: {}
+
+jobs:
+  release:
+    if: >-
+      github.event_name == 'workflow_run' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.conclusion == 'success'
+    permissions:
+      contents: write
+      pull-requests: write
+    uses: roquerodrigo/workflows/.github/workflows/release-please.yml@main
+    secrets:
+      release-token: ${{ secrets.RELEASE_PLEASE_PAT }}
+
+  sync-uv-lock:
+    needs: release
+    if: needs.release.outputs.release-pr != ''
+    permissions:
+      contents: read
+    uses: roquerodrigo/workflows/.github/workflows/sync-uv-lock.yml@main
+    with:
+      release-pr: ${{ needs.release.outputs.release-pr }}
+    secrets:
+      release-token: ${{ secrets.RELEASE_PLEASE_PAT }}
+
+  publish:
+    needs: release
+    if: >-
+      always() && (
+        github.event_name == 'workflow_dispatch' ||
+        needs.release.outputs.release-created == 'true'
+      )
+    permissions:
+      contents: read
+    uses: roquerodrigo/workflows/.github/workflows/publish-pypi.yml@main
+    with:
+      package: tuya-ble-sdk
+      ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release.outputs.tag-name }}
+    secrets:
+      pypi-token: ${{ secrets.PYPI_API_TOKEN }}

tuya_ble_sdk-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+dist/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

tuya_ble_sdk-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+# Hooks run through `uv run`, so they use the exact ruff and mypy versions
+# pinned in the lint dependency group. A hook that installs its own copy drifts
+# from CI the moment the pin moves.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        pass_filenames: false
+        types: [python]

tuya_ble_sdk-0.1.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.1"
+}

tuya_ble_sdk-0.1.1/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## [0.1.1](https://github.com/roquerodrigo/tuya-ble-sdk/compare/v0.1.0...v0.1.1) (2026-08-19)
+
+
+### Features
+
+* implement the Tuya BLE protocol ([f309745](https://github.com/roquerodrigo/tuya-ble-sdk/commit/f309745b2a62b67af4cace38ae7ecfca2b8cf7a4))
+* scaffold the Tuya BLE SDK package ([8242a3e](https://github.com/roquerodrigo/tuya-ble-sdk/commit/8242a3e7bcdccdf62f7b4385aee9d6fa2ca7d757))
+
+
+### Bug Fixes
+
+* connect at the first sighting instead of after the whole scan ([a612982](https://github.com/roquerodrigo/tuya-ble-sdk/commit/a612982a51b0b3ca0fe5c2ac7dbfa345215e3993))
+* connect at the first sighting instead of after the whole scan ([b81dd11](https://github.com/roquerodrigo/tuya-ble-sdk/commit/b81dd1180359b44832d506f8071bd85621221b55))
+* hash the advertised product record as broadcast ([be4c892](https://github.com/roquerodrigo/tuya-ble-sdk/commit/be4c892439a50ec4c163f61044a2d8abd811d085))
+* reset the framing state between two sessions of one client ([57059c2](https://github.com/roquerodrigo/tuya-ble-sdk/commit/57059c2b1a23b0517b31704108efcff9b8ac1fe9))
+* treat a report with no datapoint as an answer ([445ad3a](https://github.com/roquerodrigo/tuya-ble-sdk/commit/445ad3ac31905679a2373c89c0b461aac0883e8e))
+
+
+### Documentation
+
+* record the unparsed signed datapoint commands ([93db2a9](https://github.com/roquerodrigo/tuya-ble-sdk/commit/93db2a9cfa1530c1ea9e74d6fd6dee1e1df08c94))
+
+
+### Tests
+
+* freeze the wire bytes of the handshake commands ([18c6e86](https://github.com/roquerodrigo/tuya-ble-sdk/commit/18c6e863cbeef7d372eb4d33ea2aacd15a774484))
+
+
+### Miscellaneous Chores
+
+* let release-please own the version ([2f0a12a](https://github.com/roquerodrigo/tuya-ble-sdk/commit/2f0a12a8b9de35f55a59fc8fb119aaf5db4958c0))

tuya_ble_sdk-0.1.1/LICENSE

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

tuya_ble_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: tuya-ble-sdk
+Version: 0.1.1
+Summary: Python SDK for Tuya Bluetooth Low Energy devices
+Project-URL: Homepage, https://github.com/roquerodrigo/tuya-ble-sdk
+Project-URL: Repository, https://github.com/roquerodrigo/tuya-ble-sdk
+Project-URL: Issues, https://github.com/roquerodrigo/tuya-ble-sdk/issues
+Author-email: Rodrigo Roque <rodrigogoncalvesroque@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,home-automation,sdk,tuya
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Requires-Dist: bleak-retry-connector>=4.4.0
+Requires-Dist: bleak>=3.0.0
+Requires-Dist: cryptography>=44.0.0
+Provides-Extra: cli
+Requires-Dist: typer>=0.12.0; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# tuya-ble-sdk
+
+Python SDK for **Tuya Bluetooth Low Energy devices**. It speaks the Tuya BLE
+GATT protocol directly — handshake, session key, encrypted frames and
+datapoints — and knows nothing about Home Assistant.
+
+Consumed by the [`ha-tuya-ble`](https://github.com/roquerodrigo/ha-tuya-ble)
+integration, which pins it from `manifest.json`.
+
+## What it does
+
+One read is one whole session: the client connects, performs the handshake,
+collects the datapoint report and disconnects. Tuya BLE sensors are battery
+powered and only listen for a moment after they advertise, so holding a
+connection open would drain them and occupy a proxy slot for nothing.
+
+```python
+from tuya_ble_sdk import TuyaBleClient, TuyaBleCredentials, parse_advertisement
+
+info = parse_advertisement(service_data, manufacturer_data)
+client = TuyaBleClient(
+    ble_device,
+    TuyaBleCredentials(uuid=info.uuid, device_id=device_id, local_key=local_key),
+)
+data_points = await client.async_read_data_points()
+```
+
+Discovery belongs to the caller: the client takes an already-resolved
+`BLEDevice`, which is what lets Home Assistant hand over a device seen through
+a Bluetooth proxy.
+
+`parse_advertisement` reads what the advertisement discloses — every field of
+the result is optional. The uuid is encrypted with the product-id record
+broadcast beside it, so no cloud call is needed to learn it; the readable
+product id, however, is only there on an **unbound** device. One bound to a
+Tuya account broadcasts an obfuscated value in its place: those bytes still
+decrypt the uuid, but they name no product, and the caller has to learn what
+the device is some other way.
+
+## Command line
+
+The optional `cli` extra installs a `tuya-ble` command:
+
+```bash
+uv run --extra cli tuya-ble scan
+uv run --extra cli tuya-ble read \
+    --address AA:BB:CC:DD:EE:FF --device-id <id> --local-key <key>
+```
+
+`scan` lists every nearby Tuya BLE device with its product id and uuid; `read`
+runs one session and prints the datapoints it reported.
+
+## Not implemented
+
+The device may report datapoints in a *signed* form (`0x8004` / `0x8005`)
+instead of the plain one this SDK reads. Those two commands are recognised and
+logged, not parsed: the reference implementation disagrees with itself about
+where the records start inside them, and no device was available to settle it.
+A device that uses them shows up as a read that reports no datapoint, with the
+command name in the debug log.
+
+## Development
+
+```bash
+uv sync                     # create .venv and install dependencies
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy src
+uv run pytest               # 90 % coverage gate
+```
+
+Runtime dependencies carry a `>=` floor and nothing else: Home Assistant pins its
+own transitive dependencies exactly, so an `==` pin here eventually contradicts
+HA's pin and the integration stops installing.
+
+## Credits
+
+The protocol implementation is derived from
+[`PlusPlus-ua/ha_tuya_ble`](https://github.com/PlusPlus-ua/ha_tuya_ble) (MIT),
+itself based on [`redphx/poc-tuya-ble-fingerbot`](https://github.com/redphx/poc-tuya-ble-fingerbot).
+
+## License
+
+[MIT](LICENSE)

tuya_ble_sdk-0.1.1/README.md

@@ -0,0 +1,84 @@
+# tuya-ble-sdk
+
+Python SDK for **Tuya Bluetooth Low Energy devices**. It speaks the Tuya BLE
+GATT protocol directly — handshake, session key, encrypted frames and
+datapoints — and knows nothing about Home Assistant.
+
+Consumed by the [`ha-tuya-ble`](https://github.com/roquerodrigo/ha-tuya-ble)
+integration, which pins it from `manifest.json`.
+
+## What it does
+
+One read is one whole session: the client connects, performs the handshake,
+collects the datapoint report and disconnects. Tuya BLE sensors are battery
+powered and only listen for a moment after they advertise, so holding a
+connection open would drain them and occupy a proxy slot for nothing.
+
+```python
+from tuya_ble_sdk import TuyaBleClient, TuyaBleCredentials, parse_advertisement
+
+info = parse_advertisement(service_data, manufacturer_data)
+client = TuyaBleClient(
+    ble_device,
+    TuyaBleCredentials(uuid=info.uuid, device_id=device_id, local_key=local_key),
+)
+data_points = await client.async_read_data_points()
+```
+
+Discovery belongs to the caller: the client takes an already-resolved
+`BLEDevice`, which is what lets Home Assistant hand over a device seen through
+a Bluetooth proxy.
+
+`parse_advertisement` reads what the advertisement discloses — every field of
+the result is optional. The uuid is encrypted with the product-id record
+broadcast beside it, so no cloud call is needed to learn it; the readable
+product id, however, is only there on an **unbound** device. One bound to a
+Tuya account broadcasts an obfuscated value in its place: those bytes still
+decrypt the uuid, but they name no product, and the caller has to learn what
+the device is some other way.
+
+## Command line
+
+The optional `cli` extra installs a `tuya-ble` command:
+
+```bash
+uv run --extra cli tuya-ble scan
+uv run --extra cli tuya-ble read \
+    --address AA:BB:CC:DD:EE:FF --device-id <id> --local-key <key>
+```
+
+`scan` lists every nearby Tuya BLE device with its product id and uuid; `read`
+runs one session and prints the datapoints it reported.
+
+## Not implemented
+
+The device may report datapoints in a *signed* form (`0x8004` / `0x8005`)
+instead of the plain one this SDK reads. Those two commands are recognised and
+logged, not parsed: the reference implementation disagrees with itself about
+where the records start inside them, and no device was available to settle it.
+A device that uses them shows up as a read that reports no datapoint, with the
+command name in the debug log.
+
+## Development
+
+```bash
+uv sync                     # create .venv and install dependencies
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy src
+uv run pytest               # 90 % coverage gate
+```
+
+Runtime dependencies carry a `>=` floor and nothing else: Home Assistant pins its
+own transitive dependencies exactly, so an `==` pin here eventually contradicts
+HA's pin and the integration stops installing.
+
+## Credits
+
+The protocol implementation is derived from
+[`PlusPlus-ua/ha_tuya_ble`](https://github.com/PlusPlus-ua/ha_tuya_ble) (MIT),
+itself based on [`redphx/poc-tuya-ble-fingerbot`](https://github.com/redphx/poc-tuya-ble-fingerbot).
+
+## License
+
+[MIT](LICENSE)

tuya_ble_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,140 @@
+[project]
+name = "tuya-ble-sdk"
+version = "0.1.1"
+description = "Python SDK for Tuya Bluetooth Low Energy devices"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Rodrigo Roque", email = "rodrigogoncalvesroque@gmail.com" }]
+keywords = ["tuya", "bluetooth", "ble", "sdk", "home-automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+]
+# Runtime dependencies carry a floor and nothing else. Home Assistant pins its
+# own transitive dependencies exactly, so an `==` pin — or an upper bound —
+# eventually contradicts HA's pin and the consuming integration stops
+# installing. Exact versions belong in the dependency groups below and in
+# uv.lock, neither of which reaches the consumer.
+dependencies = [
+    "bleak>=3.0.0",
+    "bleak-retry-connector>=4.4.0",
+    "cryptography>=44.0.0",
+]
+
+[project.optional-dependencies]
+cli = [
+    "typer>=0.12.0",
+]
+
+[project.scripts]
+tuya-ble = "tuya_ble_sdk.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/roquerodrigo/tuya-ble-sdk"
+Repository = "https://github.com/roquerodrigo/tuya-ble-sdk"
+Issues = "https://github.com/roquerodrigo/tuya-ble-sdk/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tuya_ble_sdk"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["tests"]
+
+[dependency-groups]
+dev = [
+    "typer==0.20.0",
+    "pytest==9.0.3",
+    "pytest-asyncio==1.4.0",
+    "pytest-cov==7.1.0",
+    "pre-commit==4.6.1",
+]
+lint = [
+    "ruff==0.16.1",
+    "mypy==2.3.0",
+]
+
+[tool.uv]
+default-groups = ["dev", "lint"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = [
+    "--strict-markers",
+    "--cov=src/tuya_ble_sdk",
+    "--cov-report=term-missing",
+    "--cov-fail-under=90",
+]
+
+[tool.mypy]
+python_version = "3.12"
+files = ["src"]
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+check_untyped_defs = false
+
+[tool.ruff]
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.format]
+exclude = ["*.md"]  # ruff 0.16 formats Python blocks in Markdown; docs keep their own layout
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed
+    "D203",    # no-blank-line-before-class (incompatible with formatter)
+    "D212",    # multi-line-summary-first-line (incompatible with formatter)
+    "COM812",  # incompatible with formatter
+    "ISC001",  # incompatible with formatter
+    "CPY001",  # copyright headers are not used in this project
+    "TID252",  # relative imports between same-package siblings are the house style
+]
+
+[tool.ruff.lint.flake8-pytest-style]
+fixture-parentheses = false
+
+[tool.ruff.lint.pyupgrade]
+keep-runtime-typing = true
+
+[tool.ruff.lint.per-file-ignores]
+"src/tuya_ble_sdk/cli.py" = [
+    "FBT001",   # a boolean-positional flag is the typer idiom
+    "FBT003",   # so is the boolean positional passed to typer.Option
+    "PLR0913",  # a command's options are its signature
+    "PLR0917",
+]
+"tests/**" = [
+    "ARG002",   # the fake peripheral mirrors bleak's signature, unused arguments included
+    "EM101",    # a literal message is fine in a throwaway test double
+    "FBT001",   # so is a boolean flag mirroring bleak's own signature
+    "FBT002",
+    "PLC0415",  # a local import keeps a helper's dependency next to its only use
+    "PT018",    # a composite assertion reads better than splitting one fact in two
+    "S324",     # tests recompute the MD5 the protocol specifies
+    "TRY003",   # a literal message is fine in a throwaway test double
+    "S101",     # assert is normal in pytest
+    "S105",     # hardcoded-password-string is fine for fake test credentials
+    "S106",     # hardcoded-password-func-arg is fine for fake test credentials
+    "D",        # no docstrings required in tests
+    "ANN",      # no type annotations required in tests
+    "ARG001",   # fixtures are used implicitly by pytest
+    "SLF001",   # testing internal methods is intentional
+    "PLR2004",  # magic numbers in test assertions are fine
+]

tuya_ble_sdk-0.1.1/release-please-config.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "python",
+  "include-component-in-tag": false,
+  "include-v-in-tag": true,
+  "bump-minor-pre-major": true,
+  "bump-patch-for-minor-pre-major": true,
+  "packages": {
+    ".": {
+      "package-name": "tuya-ble-sdk",
+      "changelog-sections": [
+        {
+          "type": "feat",
+          "section": "Features"
+        },
+        {
+          "type": "fix",
+          "section": "Bug Fixes"
+        },
+        {
+          "type": "perf",
+          "section": "Performance Improvements"
+        },
+        {
+          "type": "revert",
+          "section": "Reverts"
+        },
+        {
+          "type": "refactor",
+          "section": "Code Refactoring"
+        },
+        {
+          "type": "deps",
+          "section": "Dependencies"
+        },
+        {
+          "type": "deps-dev",
+          "section": "Development Dependencies"
+        },
+        {
+          "type": "docs",
+          "section": "Documentation"
+        },
+        {
+          "type": "build",
+          "section": "Build System"
+        },
+        {
+          "type": "ci",
+          "section": "Continuous Integration"
+        },
+        {
+          "type": "test",
+          "section": "Tests"
+        },
+        {
+          "type": "style",
+          "section": "Styles"
+        },
+        {
+          "type": "chore",
+          "section": "Miscellaneous Chores"
+        }
+      ]
+    }
+  }
+}