Skip to content

Add optional GATT service compliance validation after device discovery #193

Description

@RonanB96

Library gap

BaseGattService.validate_service() can check required/optional/conditional characteristics against a discovered set, but Device.discover_services() never runs compliance checks. Consumers scanning unknown devices get UUID→class mapping only, with no “is this Battery Service missing 0x2A19?” feedback.

Profiles are not readable as bytes — compliance is inferred from discovered service/characteristic UUID sets (see research in docs/codebase/CONCERNS.md).

Background (citations)

  • Service validation API: src/bluetooth_sig/gatt/services/base.py (validate_service, validate_bluetooth_sig_compliance)
  • Discovery today: src/bluetooth_sig/device/connected.py (discover_services) — caches services/chars, no validation
  • Example service with required/optional maps: src/bluetooth_sig/gatt/services/environmental_sensing.py
  • Permitted-characteristic YAML exists but is not wired to runtime: bluetooth_sig/assigned_numbers/profiles_and_services/ess/ess_permitted_characteristics.yaml, src/bluetooth_sig/registry/profiles/permitted_characteristics.py

Suggested approach

  1. Add an optional API on Device (or helper on translator/service layer), e.g. validate_discovered_services() -> list[ServiceValidationResult], invoked after discover_services().
  2. Build validation input from discovered UUID sets (no extra BLE reads required).
  3. Return structured, human-readable issues (missing mandatory chars, unexpected extras) using existing ServiceValidationResult types if available.
  4. Do not auto-run on every connect — opt-in to avoid overhead.

Out of scope

  • Wiring PermittedCharacteristicsRegistry into hot path (optional future enhancement)
  • BLE transport / reading characteristic values during validation

Acceptance criteria

  • Opt-in validation API documented in docs/source/how-to/usage.md or ble-integration.md
  • Tests with mocked discovery data: compliant Battery Service + non-compliant case (missing Battery Level)
  • just qa passes

Key files to read first

  • src/bluetooth_sig/device/device.py
  • src/bluetooth_sig/gatt/services/base.py
  • src/bluetooth_sig/types/ (search ServiceValidationResult)
  • tests/device/ for Device test patterns

Consumer value

Helps apps answer “what does this device expose?” without deep GATT knowledge — aligned with library mission (docs/source/explanation/what-it-solves.md).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions