Skip to content

README.md

Latest commit

 

History

History
176 lines (125 loc) · 8.48 KB

README.md

File metadata and controls

176 lines (125 loc) · 8.48 KB

iTag BLE for Home Assistant

iTag BLE

Turn inexpensive BLE iTag key finders into wireless buttons for Home Assistant. These tags are often sold as iTag, iTag BLE, Smart Tag, Smart Finder, Key Finder, Bluetooth Key Finder, Anti-Lost Alarm, Anti-Lost Tracker, Finder Tag, PALMEXX iTag Key Finder, and similar clone names.

Each tag can be used as a compact smart home button: keep one on your keys, next to the bed, under a desk, or use it as a panic button. Home Assistant receives button press events and can run any automation you build around them.

Russian documentation

Installation

HACS

  1. Open HACS in Home Assistant.
  2. Find iTag BLE.
  3. Select Download.
  4. Restart Home Assistant when Home Assistant asks you to.
  5. Go to Settings -> Devices & services -> Integrations.
  6. Press the button on the iTag once near your Bluetooth adapter.
  7. Wait until Home Assistant receives BLE advertising packets from the tag and detects the device. This can take a little while.
  8. Home Assistant should show a discovered iTag BLE device in the integrations list.
  9. Select the discovered device and finish the setup.

If the tag does not appear automatically, choose Add integration -> iTag BLE. The setup flow can list discovered Bluetooth candidates, and it also supports manual MAC address entry.

Manual

  1. Copy custom_components/itag_bt from this repository to your Home Assistant configuration directory: /config/custom_components/itag_bt/
  2. Restart Home Assistant.
  3. Press the iTag button once near your Bluetooth adapter.
  4. Add the discovered device from Settings -> Devices & services -> Integrations, or use Add integration -> iTag BLE.

You can add the integration more than once, one config entry per tag.

Features

  • binary_sensor for the iTag button press using the FFE0 service and FFE1 notify characteristic.
  • switch for immediate beep control using Immediate Alert 0x1802 / Alert Level 0x2A06 (0x02 beep, 0x00 silent).
  • switch (Link Alert) for the Link Loss alert policy using service 0x1803 / characteristic 0x2A06.
  • sensor for battery level using Battery Service 0x180F / Battery Level 0x2A19.
  • Passive BLE advertisement monitoring for the selected MAC address.
  • Automatic connection when the selected tag advertises.
  • FFE1 notification subscription and Home Assistant bus events for connect, disconnect, and button press.
  • Immediate Alert keepalive that periodically writes 0x00 to 0x1802:2A06 to reduce unwanted beeping.

Requirements

  • Home Assistant 2026.3.0 or newer.
  • The built-in Home Assistant Bluetooth integration enabled.
  • One of the following BLE access options:
    • a local Bluetooth adapter on the Home Assistant host;
    • ESPHome Bluetooth Proxy with connectable BLE support;
    • Home Assistant Container/Core on Linux with BlueZ and access to the Bluetooth adapter.
  • For Home Assistant Container setups, Bluetooth usually requires:
    • network_mode: host;
    • access to D-Bus/BlueZ and the Bluetooth adapter;
    • in some installations, privileged: true.
  • Enough free GATT connection slots on the adapter. Cheap BLE adapters and the built-in Raspberry Pi Bluetooth adapter may only keep a small number of active GATT sessions stable.
  • The tag must be within Bluetooth range and advertising. Many iTag clones wake up after pressing the button once near the adapter.

Discovery

The integration uses the Home Assistant Bluetooth cache and shows likely iTag candidates in the setup flow. A candidate is detected by the advertised name (iTag, ITAG, Key Finder, PALMEXX) or by the FFE0 service UUID.

Home Assistant can also show a discovered device card automatically under Settings -> Devices & services -> Integrations when the tag advertises a matching name or service. Pressing the button once is enough to wake many iTag clones and make them advertise.

If a clone does not advertise a recognizable name or service, the setup flow can still show nearby connectable BLE devices when no stronger iTag candidates are available. In that case, use the device name and RSSI as hints: the closer RSSI is to zero, the closer the device is to the adapter.

Entities

The integration creates one Home Assistant device for each configured tag. Entities use the tag name you choose during setup:

  • binary_sensor.<name> Button - turns on briefly when the button is pressed.
  • switch.<name> Beep - starts or stops the immediate beep.
  • switch.<name> Link Alert - controls the Link Loss alert level where supported by the tag firmware.
  • sensor.<name> Battery - shows battery level in percent when the tag exposes Battery Service.

Entities use unique IDs with the _v2 suffix.

How It Works

The integration registers a passive BLE advertisement listener. When the selected MAC address is seen, it schedules a GATT connection through the Home Assistant Bluetooth manager.

After connecting, it:

  • subscribes to FFE1 notifications for button presses;
  • writes 0x00 to Alert Level 0x2A06 to silence Immediate Alert;
  • periodically sends 0x1802:2A06 = 0x00 as a keepalive;
  • applies the Link Loss policy only to 0x1803:0x2A06 using write-with-response and readback.

The integration fires these Home Assistant bus events:

  • Button press: itag_bt_button_<MAC>
  • Connected: itag_bt_connected_<MAC>
  • Disconnected: itag_bt_disconnected_<MAC>

Supported GATT UUIDs

  • Button: 0000FFE1-0000-1000-8000-00805F9B34FB (notify), service FFE0.
  • Immediate beep: 00002A06-0000-1000-8000-00805F9B34FB on service 0x1802.
  • Link Loss: service 0x1803 / characteristic 0x2A06.
  • Battery: 00002A19-0000-1000-8000-00805F9B34FB on service 0x180F.

Most iTag clones use the same UUIDs. Some variants may not expose Battery Service, and some ignore the Link Loss alert level even when the characteristic exists.

Notes and Limitations

  • The first button press after sleep may only wake the tag. The next press is usually delivered after the connection is ready.
  • Raspberry Pi built-in Bluetooth can handle only a limited number of simultaneous GATT sessions.
  • Some iTag clones beep on disconnect because of their Link Loss firmware behavior. The integration silences Immediate Alert after connect, but a short beep during Home Assistant restart can still happen.
  • Some clones ignore writes to 0x1803:2A06; in that case the Link Alert switch cannot change the physical disconnect beep behavior.
  • If you use other BLE integrations, make sure they do not keep a GATT connection open to the same tag.

Debug Logging

Add this to configuration.yaml:

logger:
  default: info
  logs:
    custom_components.itag_bt: debug
    homeassistant.components.bluetooth: debug

Look for custom_components.itag_bt and homeassistant.components.bluetooth messages in Settings -> System -> Logs.

For Home Assistant running in Docker:

docker logs -f --tail=100 homeassistant

Useful log lines include:

  • ADV seen, scheduling connect
  • connected + notify
  • keepalive start/stop
  • battery -> <value>

Repository Layout

custom_components/itag_bt/
  __init__.py        # client registration, advertisement watcher, platform loading
  brand/             # local Home Assistant brand images
  const.py           # domain, platforms, UUIDs, signals, shared constants
  helpers.py         # MAC validation, device_info, iTag advertisement detection
  manifest.json      # integration metadata
  strings.json       # default English setup flow strings
  translations/ru.json
  config_flow.py     # Bluetooth discovery and manual setup flow
  coordinator.py     # BLE client: connect, notify, keepalive, events, beep, battery
  binary_sensor.py   # button entity
  switch.py          # Immediate Alert and Link Alert switches
  sensor.py          # battery entity

Compatibility

Tested with Raspberry Pi 4B built-in Bluetooth, BlueZ, and Home Assistant Core in Docker using network_mode: host and privileged: true.

Confirmed on a PALMEXX iTag clone:

  • FFE1 button notifications;
  • Immediate Alert 0x1802/0x2A06;
  • Battery Service 0x180F/0x2A19;
  • Link Loss behavior depends on clone firmware.

License

MIT. See LICENSE.

Home Assistant, iTag, PALMEXX, and Bluetooth names are used only to describe compatibility. This project is not an official Home Assistant integration and is not affiliated with the manufacturers of these tags.