# iTag BLE Bluetooth Tracker
# Copyright 2026 Pigs Can Fly Labs LLC
# SPDX-License-Identifier: Apache-2.0

device:
  name: "iTag BLE Key Finder"
  manufacturer: "Unbranded / various OEMs"
  manufacturer_status: "unsupported"
  protocol: "ble"
  notes: >
    Ultra-cheap ($1-2) BLE key finder / anti-loss tracker. CR2032 battery,
    LED and buzzer. Hard-coded public MAC address — a privacy concern
    because the MAC can be tracked.

    PROTOCOL: three standard BLE services:
    - Immediate Alert service (0x1802): characteristic 0x2A06 for
      triggering buzzer/LED. Write 0x00=off, 0x01=mild alert, 0x02=high
      alert (buzzer + LED).
    - Battery service (0x180F): characteristic 0x2A19 for reading battery
      percentage.
    - Button service (0xFFE0): characteristic 0xFFE1 for button-press
      notifications. Nearly every iTag manufacturer uses this quasi-standard
      characteristic for button events.

    BUTTON NOTIFICATIONS: subscribe to 0xFFE1 notifications. Device sends
    data on each button press. The CCCD descriptor (0x2902) may not exist
    — some firmware requires direct subscribe calls. Double-click detection
    uses a ~300ms debounce window.

    BONDING: community reports that some models drain batteries rapidly
    if NOT bonded. Bonding is recommended but not strictly required for
    operation.

    DISCOVERY: advertised name patterns vary ("iTAG", "itag", "ITAG",
    etc.). Service UUIDs 0x1802, 0x180F, and 0xFFE0 are present.

    CONFIDENCE: HIGH for alert service, button service, battery service
    UUIDs and characteristics — sourced from thejeshgn.com RE blog,
    Gadgetbridge wiki, and Edzelf/Itag ESP32 Arduino project.
    MEDIUM: exact name patterns (vary by manufacturer).

  identification:
    service_uuids:
      - "00001802-0000-1000-8000-00805f9b34fb"

  discovery:
    methods:
      - type: "ble_scan"
        ble:
          service_uuids:
            - "00001802-0000-1000-8000-00805f9b34fb"
    identity:
      stable_keys: ["address"]
      display: "local_name"
    static_ip_required: false

  setup:
    required: false
    confidence: "medium"
    notes: >
      Bonding recommended to prevent battery drain (community reports).
      Basic alert and button functions work without bonding.
    methods:
      - type: "ble_direct"
        verified: true
        description: >
          Scan for 0x1802 Immediate Alert service, connect, optionally bond.
          Subscribe to 0xFFE1 for button notifications.
        ble:
          pairing_required: false
        steps:
          - action: "Ensure iTag has a working battery."
            actor: "user"
            request:
              protocol: "ble_gatt"
          - action: >
              Scan for 0x1802 (Immediate Alert) service in advertisements
              and connect.
            actor: "client"
          - action: >
              Write alert level to 0x2A06 (0x02 = high alert for buzzer/LED).
            actor: "client"
          - action: >
              Subscribe to 0xFFE1 notifications for button press events.
            actor: "client"
    factory_reset:
      confidence: "low"
      effect: >
        Remove CR2032 battery to reset. No stored state.
      procedures:
        - name: "Battery removal"
          steps:
            - action: "Remove CR2032 battery for 10 seconds and reinsert."
              actor: "user"
              expect: "Device powers on and advertises."
    rejoin:
      in_place_supported: true
      requires_factory_reset: false
      notes: >
        If bonded, remove bond from OS Bluetooth settings before
        reconnecting from a different controller.
    credentials:
      wifi_passphrase_protection: "not_applicable"
      stored_on_device: []
      issued_to_client: []
      notes: >
        No auth. Hard-coded public MAC address is a privacy tracking
        risk. Warn users that the MAC can be used to track the tag.

services:
  - uuid: "00001802-0000-1000-8000-00805f9b34fb"
    name: "Immediate Alert Service"
    notes: >
      Standard BLE Immediate Alert service. Triggers buzzer and LED.
    characteristics:
      - uuid: "00002a06-0000-1000-8000-00805f9b34fb"
        name: "Alert Level"
        properties: ["write", "write_without_response"]
        notes: >
          Write alert level: 0x00=off, 0x01=mild alert, 0x02=high alert
          (activates buzzer + LED). Write-without-response is commonly
          supported.

  - uuid: "0000ffe0-0000-1000-8000-00805f9b34fb"
    name: "Button Service"
    notes: >
      Quasi-standard button notification service. Almost every iTag
      manufacturer uses this UUID.
    characteristics:
      - uuid: "0000ffe1-0000-1000-8000-00805f9b34fb"
        name: "Button"
        properties: ["notify", "read"]
        notes: >
          Button press notifications. CCCD descriptor 0x2902 may not exist
          on all models — use direct subscribe if CCCD write fails.
          Double-click detection with ~300ms debounce window.

  - uuid: "0000180f-0000-1000-8000-00805f9b34fb"
    name: "Battery Service"
    characteristics:
      - uuid: "00002a19-0000-1000-8000-00805f9b34fb"
        name: "Battery Level"
        properties: ["read", "notify"]
        notes: "Read battery percentage (uint8, 0-100)."

entities:
  - platform: "switch"
    name: "Alert"
    state_characteristic: "00002a06-0000-1000-8000-00805f9b34fb"
  - platform: "binary_sensor"
    name: "Button"
    state_characteristic: "0000ffe1-0000-1000-8000-00805f9b34fb"
  - platform: "sensor"
    name: "Battery"
    state_characteristic: "00002a19-0000-1000-8000-00805f9b34fb"