bluetooth-sig 0.1.1__tar.gz

bluetooth_sig-0.1.1/.editorconfig

@@ -0,0 +1,37 @@
+# https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{html,css,js,json,sh,yml,yaml}]
+indent_size = 2
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+[Makefile]
+indent_style = tab
+indent_size = unset
+
+# Ignore binary or generated files
+[*.{png,jpg,gif,ico,woff,woff2,ttf,eot,svg,pdf}]
+charset = unset
+end_of_line = unset
+indent_style = unset
+indent_size = unset
+trim_trailing_whitespace = unset
+insert_final_newline = unset
+max_line_length = unset
+
+[*.{diff,patch}]
+trim_trailing_whitespace = false

bluetooth_sig-0.1.1/.github/ISSUE_TEMPLATE/general-task.md

@@ -0,0 +1,203 @@
+---
+name: General Development Task
+about: Standard template for development tasks with testing and workflow requirements
+title: '[TASK] '
+labels: ['enhancement']
+assignees: []
+---
+
+## 🎯 Task Description
+
+**Brief Summary:**
+<!-- Clearly describe what needs to be done -->
+
+**Motivation:**
+<!-- Why is this task needed? What problem does it solve? -->
+
+## 📋 Implementation Requirements
+
+### Core Changes
+
+- [ ] <!-- List specific changes needed -->
+- [ ] <!-- Be precise about what files/functions to modify -->
+- [ ] <!-- Include any new files that need to be created -->
+
+### Code Quality Standards
+
+- [ ] Follow existing code patterns and naming conventions
+- [ ] Add comprehensive docstrings and type hints
+- [ ] Ensure all functions have proper error handling
+- [ ] Use descriptive variable and function names
+- [ ] Follow the project's architectural patterns
+
+## 🧪 Testing Requirements
+
+### Unit Tests (MANDATORY)
+
+- [ ] Create/update unit tests for all new functionality
+- [ ] Ensure 100% test coverage for new code
+- [ ] Test both success and failure scenarios
+- [ ] Add edge case testing (empty inputs, boundary values, etc.)
+- [ ] Use appropriate test fixtures and mocking
+
+### Integration Tests
+
+- [ ] Test integration with existing components
+- [ ] Verify compatibility with Home Assistant integration
+- [ ] Test real device scenarios if applicable
+- [ ] Validate registry validation tests pass
+
+### Test Execution Checklist
+
+- [ ] Run: `python -m pytest tests/ -v`
+- [ ] All tests must pass with 0 failures
+- [ ] No test warnings or deprecation notices
+
+## 🔍 Code Quality Validation
+
+### Script-Based Formatting and Linting (MANDATORY)
+
+**CRITICAL: These commands MUST be run after implementation and ALL issues fixed:**
+
+- [ ] Run: `./scripts/format.sh --fix` (fix all formatting issues)
+- [ ] Run: `./scripts/format.sh --check` (verify formatting is correct)
+- [ ] Run: `./scripts/lint.sh --all` (run all linting checks)
+- [ ] **ALL linting checks MUST pass: flake8 + pylint 10.00/10 + shellcheck**
+- [ ] **Zero violations allowed in any linting tool**
+
+### Individual Tool Validation (For Debugging)
+
+- [ ] Run: `./scripts/lint.sh --flake8` (style checking)
+- [ ] Run: `./scripts/lint.sh --pylint` (code analysis - MUST score 10.00/10)
+- [ ] Run: `./scripts/lint.sh --shellcheck` (shell script validation)
+- [ ] Run: `./scripts/format.sh --black` (Python code formatting check)
+- [ ] Run: `./scripts/format.sh --isort` (import sorting check)
+
+### Legacy Commands (Deprecated - Use Scripts Above)
+
+- [ ] ~~Run: `python -m black src/ tests/` (format code)~~
+- [ ] ~~Run: `python -m flake8 src/ tests/` (style checking)~~
+- [ ] ~~Run: `python -m pylint src/ble_gatt_device` (code analysis)~~
+- [ ] **Use `./scripts/format.sh` and `./scripts/lint.sh` instead**
+
+### Manual Validation
+
+- [ ] Run: `find src -name "*.py" -exec python -m py_compile {} \;` (syntax check)
+- [ ] Run: `python -c "import ble_gatt_device; print('✅ Import successful')"`
+- [ ] Test import of any new modules/classes
+- [ ] Verify no import errors or circular dependencies
+
+## 🚀 GitHub Workflow Compliance
+
+### CI/CD Requirements (MANDATORY)
+
+- [ ] All GitHub Actions workflows must pass
+- [ ] Pull request checks must be green
+- [ ] No failing status checks allowed
+- [ ] Branch is up-to-date with main before merging
+
+### Pre-commit Validation
+
+Before creating pull request, run these commands:
+
+```bash
+# Activate virtual environment
+source .venv/bin/activate
+
+# MANDATORY: Format and validate code using scripts
+./scripts/format.sh --fix           # Fix all formatting issues
+./scripts/format.sh --check         # Verify formatting is correct
+./scripts/lint.sh --all             # Run ALL linting checks (flake8 + pylint + shellcheck)
+
+# Run comprehensive tests
+python -m pytest tests/ -v
+
+# Manual validation
+find src -name "*.py" -exec python -m py_compile {} \;
+python -c "import ble_gatt_device; print('✅ Framework ready')"
+```
+
+**CRITICAL: All format and lint scripts must pass with zero issues before creating pull request.**
+
+## 📁 Files to Modify/Create
+
+### Expected File Changes
+
+- [ ] `src/ble_gatt_device/...` <!-- List specific files -->
+- [ ] `tests/test_...` <!-- List test files -->
+- [ ] Update relevant `__init__.py` files for new modules
+- [ ] Update documentation if needed
+
+### Registry Updates (if applicable)
+
+- [ ] Update `src/ble_gatt_device/gatt/services/__init__.py`
+- [ ] Update `src/ble_gatt_device/gatt/characteristics/__init__.py`
+- [ ] Ensure proper registration in respective registries
+
+## ✅ Definition of Done
+
+### Functional Requirements
+
+- [ ] All specified functionality is implemented
+- [ ] Code follows project architectural patterns
+- [ ] No breaking changes to existing functionality
+- [ ] Home Assistant integration works correctly
+
+### Quality Gate (ALL MUST PASS)
+
+- [ ] **Script-based format check passes: `./scripts/format.sh --check`**
+- [ ] **Script-based lint check passes: `./scripts/lint.sh --all`**
+- [ ] **Pylint score: 10.00/10**
+- [ ] **Zero flake8 violations**
+- [ ] **Zero shellcheck issues**
+- [ ] **All tests pass: 0 failures**
+- [ ] **All GitHub workflows pass**
+- [ ] **No import errors or syntax issues**
+
+### Documentation
+
+- [ ] Add/update docstrings for all new functions/classes
+- [ ] Update relevant documentation files if needed
+- [ ] Include usage examples in docstrings
+- [ ] Document any new configuration options
+
+## 🔗 Related Information
+
+**Dependencies:**
+<!-- List any dependencies on other issues or external factors -->
+
+**References:**
+
+- [Bluetooth SIG Assigned Numbers](https://www.bluetooth.com/specifications/assigned-numbers/)
+- [GATT Services & Characteristics Specifications](https://www.bluetooth.com/specifications/specs/)
+- Local YAML Registry Files:
+  - Services: `bluetooth_sig/assigned_numbers/uuids/service_uuids.yaml`
+  - Characteristics: `bluetooth_sig/assigned_numbers/uuids/characteristic_uuids.yaml`
+  - Specifications: `bluetooth_sig/gss/org.bluetooth.characteristic.*.yaml`
+
+**Breaking Changes:**
+<!-- Note if this introduces any breaking changes -->
+
+## 🎯 Success Criteria
+
+**The task is complete when:**
+
+1. All implementation requirements are met
+2. All tests pass with 100% success rate
+3. **MANDATORY: `./scripts/format.sh --check` passes with zero issues**
+4. **MANDATORY: `./scripts/lint.sh --all` passes with zero issues**
+5. All GitHub workflows are green
+6. Code is properly documented and follows project patterns
+7. No regressions in existing functionality
+
+**Note for Copilot:**
+
+- **MANDATORY**: Run `./scripts/format.sh --fix` and `./scripts/lint.sh --all` after implementation
+- **TASK NOT COMPLETE**: Until all script-based quality checks pass with zero issues
+- Follow the BLE GATT Device project's existing patterns and architecture
+- Use the bluetooth_sig submodule for UUID lookups (check YAML files above)
+- Ensure all characteristics implement proper `decode_value()` methods with appropriate data types
+- Follow the 4-stage UUID name resolution system
+- Test against real device scenarios when possible
+- Maintain backward compatibility with existing implementations
+- Reference Bluetooth SIG specifications for data formats and units

bluetooth_sig-0.1.1/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+* Bluetooth SIG Python version:
+* Python version:
+* Operating System:
+
+### Description
+
+Describe what you were trying to get done.
+Tell us what happened, what went wrong, and what you expected to happen.
+
+### What I Did
+
+```
+Paste the command(s) you ran and the output.
+If there was a crash, please include the traceback here.
+```

bluetooth_sig-0.1.1/.github/ai-agent-characteristic-rules.md

@@ -0,0 +1,79 @@
+# AI Agent Rules — GATT Characteristic Implementations
+
+Purpose
+
+Provide a concise, enforceable checklist for automated agents or contributors implementing files under `src/bluetooth_sig/gatt/characteristics/`.
+
+Core principle
+
+- Characteristics implement ONLY field-specific parsing, sentinel mapping, scaling and construction of typed return values.
+- All generic validation (length, type, range) MUST be declared as class attributes and is enforced by `BaseCharacteristic.parse_value()`.
+
+Templates & reuse
+
+- Reuse `templates` helpers when a characteristic matches an existing template. Do not copy template parsing into concrete characteristics.
+- Extend templates by composition/wrapping rather than duplicating parsing code.
+
+Registry (GSS/YAML) guidance
+
+- YAML registry entries are authoritative for field sizes, data types and encoding. Consult the YAML entry before implementing parsing.
+- Use these helpers where available:
+  - `get_yaml_data_type()` — select DataParser primitive
+  - `get_yaml_field_size()` — set `expected_length` / `min_length`
+  - `is_signed_from_yaml()` — determine signed vs unsigned
+
+Data parsing rules
+
+- Use `DataParser` and `ieee11073` helpers for primitive reads/writes (e.g. `parse_int16`, `parse_int32`).
+- Use a `pos` offset for multi-field parsing and let helpers raise `InsufficientDataError` when bytes are insufficient.
+- Map sentinel/special values to `None` only after parsing the raw field.
+
+Constants & magic numbers
+
+- Replace inline magic numbers with named constants and a one-line comment (lengths, sentinel values, scales, masks, shifts).
+- Constants placement:
+  - Shared across characteristics → `src/bluetooth_sig/gatt/constants.py` or `src/bluetooth_sig/types/constants.py`.
+  - Characteristic-local → class-level constant inside the characteristic file.
+
+Encode/decode symmetry
+
+- Implement `encode_value` as the logical inverse of `decode_value` using `DataParser.encode_*` helpers. Ensure field sizes, endianness and scales match the YAML spec.
+
+Bitfields & flags
+
+- Define masks/shifts and prefer `enum.IntFlag` when reusable. Return typed booleans or flags in outputs and document bit meanings in the docstring.
+- Do NOT use plain `int` for enumerated values — use `enum.Enum` or `enum.IntFlag` for type safety and readability.
+- For bit fields representing presence flags or other bit masks, use `enum.IntFlag` for type safety.
+
+Forbidden patterns (MUST NOT)
+
+- Do NOT perform length, range, or type validation inside `decode_value`/`encode_value` — `BaseCharacteristic` handles these.
+- Do NOT reimplement endianness/signed parsing or use manual `int.from_bytes` where `DataParser` exists.
+- Do NOT hardcode SIG UUIDs in parsing logic; use registry resolution or `_info = CharacteristicInfo(...)` only for vendor metadata.
+- Do NOT return sentinel integers or raw bytes as "unknown" — map to `None` explicitly.
+
+Docs & metadata
+
+- Docstring must include: UUID/name, format/length, endianness, units, scale factor, sentinel values and mapping, bitfield layout, raised exceptions, and an example hex payload.
+
+Testing requirements
+
+- Each characteristic must include tests: one success case and at least two failure cases (insufficient data + invalid/out-of-range). Tests must assert exception types and `CharacteristicData` semantics.
+
+CI / machine checks (suggested)
+
+- Fail if `int.from_bytes` appears in `gatt/characteristics/`.
+- Fail if `len(data)` checks or `raise InsufficientDataError` occur inside `decode_value`/`encode_value` for checks that class attributes cover.
+- Fail if inline magic numeric literals appear near parsing code.
+
+Example automation regexes (adjust before use)
+
+- `\bint\.from_bytes\b`
+- `if\s+len\(data\)\s*[!=<]`
+- `raise\s+InsufficientDataError\(`
+- `\b0x[0-9A-Fa-f]+\b` (for hex literals near parsing)
+
+Quick DO / DO NOT
+
+- DO: declare `expected_length = 4` then `raw = DataParser.parse_int32(data, 0, signed=True); return None if raw == VALUE_NOT_KNOWN else raw * SCALE`
+- DO NOT: `if len(data) != 4: raise InsufficientDataError(...); raw = int.from_bytes(data[:4], 'little', signed=True)`

bluetooth_sig-0.1.1/.github/copilot-instructions.md

@@ -0,0 +1,114 @@
+# Bluetooth SIG Standards Library - AI Agent Guidelines
+
+**TL;DR**: Check docs → Run tests → Fix → Lint → Done
+
+---
+
+## ABSOLUTE PROHIBITIONS (Read This First)
+
+**The following practices are FORBIDDEN. No exceptions. Violating these breaks the architecture:**
+
+### ❌ NEVER Use:
+- `TYPE_CHECKING` blocks or lazy imports in core logic
+- Hardcoded UUID strings (use the lib to resolve from registry)
+- `from typing import Optional` (use `Type | None`)
+- Bare `except:` or silent `pass`
+- Raw `dict`/`tuple` returns (use `msgspec.Struct`)
+- Untyped public function signatures
+
+**If you catch yourself typing any of the above, STOP. They are architectural violations.**
+
+---
+
+## Core Principles (Non-Negotiable)
+
+### 1. Research First (MANDATORY)
+Consult official Bluetooth SIG specs and Python stdlib docs before implementing. State source explicitly: "Per [X documentation]..." or note if unavailable.
+
+### 2. Think Before Acting
+Use available thinking tools before making changes—plan approach, edge cases, and implications.
+
+### 3. Architecture Boundaries (ABSOLUTE)
+`src/bluetooth_sig/` must remain framework-agnostic. NO imports from `homeassistant`, `bleak`, `simplepyble`, or any backend. Translation layer supports multiple backends.
+
+### 4. No Untested Code
+Every new function needs tests: success + 2 failure cases minimum. Run `python -m pytest tests/ -v` before claiming completion.
+
+### 5. Quality Gates Must Pass
+Run `./scripts/lint.sh --all` before completion (pipe to file, don't grep output). Fix issues, don't suppress them. For iteration, rerun only failing linter (`./scripts/lint.sh --mypy`), then rerun all at end.
+
+### 6. Documentation Policy
+- Updating documentation (./docs/) will be asked directly if needed.
+- If making code changes that will break the code blocks in the docs, update those code blocks too.
+- Inline comments and docstrings (mandatory for new code)
+
+---
+
+## Workflow (Every Change)
+
+1. **Research** → Consult specs, verify requirements, cite sources
+2. **Think** → Plan approach, edge cases, implications
+3. **Implement** → Pure functions/dataclasses following patterns (see path-specific instructions)
+4. **Test** → Success + 2 failure cases minimum
+5. **Validate** → Run quality gates (below)
+
+---
+
+## Quality Gates (Must ALL Pass)
+
+```bash
+./scripts/format.sh --fix
+./scripts/format.sh --check
+./scripts/lint.sh --all
+python -m pytest tests/ -v
+```
+
+ALL must pass with zero errors. No exceptions.
+
+---
+
+## Architecture Overview
+
+**Two-Tier API Design:**
+
+1. **Direct Classes** (Type-Safe, Recommended):
+   ```python
+   from bluetooth_sig.gatt.characteristics import BatteryLevelCharacteristic
+   char = BatteryLevelCharacteristic()
+   level: int = char.parse_value(bytearray([85]))  # IDE knows return type
+   ```
+
+2. **Translator** (Dynamic, For Unknown UUIDs):
+   ```python
+   from bluetooth_sig import BluetoothSIGTranslator
+   translator = BluetoothSIGTranslator()
+   result = translator.parse_characteristic("2A19", bytearray([85]))  # Returns Any
+   ```
+
+Path-specific instructions (python-implementation, testing, bluetooth-gatt) load automatically based on file type.
+
+---
+
+## Authoritative References
+
+Must consult and cite when adding non-trivial logic:
+- Bluetooth SIG Assigned Numbers: https://www.bluetooth.com/specifications/assigned-numbers/
+- Python Standard Library: https://docs.python.org/
+- Project guides: `docs/AGENT_GUIDE.md`, `docs/BLUETOOTH_SIG_ARCHITECTURE.md`
+
+If spec unavailable: state explicitly, note verification needed.
+
+---
+
+## Completion Checklist
+
+Task complete when ALL true:
+□ Submodule initialized, documentation cited
+□ Tests pass (success + 2 failures), quality gates pass
+□ No ABSOLUTE PROHIBITIONS violated (TYPE_CHECKING, lazy imports, hardcoded UUIDs, framework imports)
+□ Type hints complete on all public functions
+
+---
+
+Following these rules is mandatory. Deviations require explicit justification.
+

bluetooth_sig-0.1.1/.github/dependabot.yml

@@ -0,0 +1,40 @@
+# Dependabot configuration for BLE GATT Device Framework
+# This file configures automatic dependency updates for Python packages and GitHub Actions
+# See: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  # Python dependencies - automatically reads from pyproject.toml
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 5
+    reviewers:
+      - "RonanB96"
+    assignees:
+      - "RonanB96"
+    commit-message:
+      prefix: "deps"
+      prefix-development: "deps-dev"
+      include: "scope"
+
+  # GitHub Actions - automatically tracks all actions in workflows
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "10:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 2
+    reviewers:
+      - "RonanB96"
+    assignees:
+      - "RonanB96"
+    commit-message:
+      prefix: "ci"
+      include: "scope"

bluetooth_sig-0.1.1/.github/instructions/bluetooth-gatt.instructions.md

@@ -0,0 +1,37 @@
+---
+applyTo: "src/bluetooth_sig/gatt/**/*.py,src/bluetooth_sig/registry/**/*.py"
+---
+
+# Bluetooth GATT Layer Guidelines
+
+## Architecture Boundaries (ABSOLUTE)
+
+**Forbidden imports in `src/bluetooth_sig/`:**
+- `from homeassistant` or any framework code
+- `from bleak` / `from simplepyble` or any BLE backend
+
+## UUID Policy (ABSOLUTE)
+
+**NEVER hardcode UUID strings.**
+
+UUIDs only in: YAML submodule, test fixtures, custom `_info` definitions.
+
+## API Consistency
+
+SIG characteristics auto-resolve UUID. Custom require `_info = CharacteristicInfo(...)`
+
+## Implementation
+
+**BaseCharacteristic handles:** Length/range/special value validation
+
+**Your `_decode_value()` only:** Parse bytes using templates, apply scaling, return typed result
+
+**Patterns:**
+- Simple value → Use template (`Uint8Template`, etc.)
+- Multi-field → Override `_decode_value()`, return `msgspec.Struct`
+- Enum/bitfield → Use `IntFlag`
+
+**Standards:**
+- Multi-byte: little-endian
+
+**Reference:** See `battery_level.py`, `heart_rate_measurement.py`, `templates.py`

bluetooth_sig-0.1.1/.github/instructions/documentation.instructions.md

@@ -0,0 +1,19 @@
+---
+applyTo: "docs/**/*.md, docs/*.md"
+---
+
+# Documentation Guidelines
+
+## Code Samples
+
+- Every code block must be runnable and validated
+- Use Sphinx cross-references: `:class:`CharacteristicData``, `:meth:`parse_characteristic``
+- Pair code with expected output
+
+## Style
+
+- Google-style docstrings (see python-implementation.instructions.md)
+- Task-oriented headings (nouns)
+- One-sentence summaries
+- Active voice, second-person
+- Keep paragraphs under three sentences

bluetooth_sig-0.1.1/.github/instructions/memory.instruction.md

@@ -0,0 +1,30 @@
+---
+applyTo: '**'
+---
+
+# Personal memory for the AI assistant
+
+preferences:
+
+- language: en-GB
+- default_shell: bash
+- communication: concise, technical, iterative progress updates
+
+project_conventions:
+
+- always consult official documentation before coding
+- run format, lint, and tests before claiming any solution works
+- never hardcode UUIDs; use registry-driven resolution
+- validate all input per SIG spec
+- raise clear, specific errors
+- add/maintain tests for all new features
+
+user_expectations:
+
+- prefers direct, actionable updates
+- values clarity and technical accuracy
+- expects agent to proactively check for duplication, clarity, and broken references
+
+notes:
+
+- remember: User prefers concise, technical updates and iterative progress.

bluetooth_sig-0.1.1/.github/instructions/python-implementation.instructions.md

@@ -0,0 +1,41 @@
+---
+applyTo: "**/*.py,**/pyproject.toml,**/requirements*.txt"
+---
+
+# Python Implementation Guidelines
+
+## Prohibited Practices (ABSOLUTE)
+
+- Hardcoded UUIDs (use registry resolution)
+- `from typing import Optional` (use `Type | None`)
+- `TYPE_CHECKING` blocks
+- Lazy/conditional imports in core logic
+- Untyped public function signatures
+- `hasattr`/`getattr` when direct access is possible
+- Bare `except:` or silent `pass`
+- Returning raw `dict` or `tuple` (use `msgspec.Struct`)
+- Magic numbers without named constants
+
+## Type Safety (MANDATORY)
+
+- All public functions MUST have complete type hints
+- Use `Type | None` not `Optional[Type]`
+- `Any` requires inline justification
+
+## Data Modelling
+
+- Use `msgspec.Struct` (frozen, kw_only)
+
+## Docstrings
+
+- Google style (Args, Returns, Raises)
+- Include spec references for non-obvious logic
+
+## Quality Gates
+
+```bash
+./scripts/format.sh --fix
+./scripts/format.sh --check
+./scripts/lint.sh --all
+python -m pytest tests/ -v
+```

bluetooth_sig-0.1.1/.github/instructions/testing.instructions.md

@@ -0,0 +1,33 @@
+---
+applyTo: "**/tests/**/*.py,**/test_*.py,**/*_test.py"
+---
+
+# Testing Requirements
+
+## Policy (MANDATORY)
+
+Every new function needs: success + 2 failure cases minimum.
+
+## Required Test Cases
+
+1. Parsing success
+2. Length violation (too short, empty)
+3. Range violation
+4. Registry resolution
+5. Encoding roundtrip
+
+## Edge Cases
+
+- Empty: `bytearray([])`
+- Boundaries: min, max, just outside
+- Sentinels: 0xFF, 0xFFFF, 0x8000
+
+## Commands
+
+```bash
+python -m pytest tests/ -v
+python -m pytest -k "battery" -v
+python -m pytest --lf
+```
+
+Tests must be deterministic. See `tests/gatt/` for patterns.