BLE iTag Button¶
This example shows how to use a cheap BLE keyring tag to trigger arbitrary events. An ESP32 is used, which provides a BLE peripheral.
These tags can be had for a couple of dollars each and run for several months on a coin cell. Using the BLE features of ESPHome, you can use these as small and cheap remotes to control any automation.
Use the configuration block below for a basic setup which will provide a binary_sensor that is momentarily turned on when the button is pressed.
You will need to find the MAC address of your tag. See the documentation for BLE Client for how to find this out. You may also wish to change the name and id fields where appropriate to suit your device(s).
Note that a maximum of three devices are supported due to limitations in the ESP32’s BLE stack.
esp32_ble_tracker: ble_client: # Replace with the MAC address of your device. - mac_address: FF:FF:20:00:0F:15 id: itag_black binary_sensor: - platform: template id: black_button name: "Black iTag Button" filters: delayed_off: 200ms sensor: # This entry registers and awaits notifications for the # characteristic that signals button presses. Each time # a notification is received, the corresponding binary_sensor # is briefly toggled. - platform: ble_client ble_client_id: itag_black name: "Black iTag btn" service_uuid: 'ffe0' characteristic_uuid: 'ffe1' notify: true update_interval: never on_notify: then: - binary_sensor.template.publish: id: black_button state: ON - binary_sensor.template.publish: id: black_button state: OFF # This entry queries the battery level. Some tags may not # support this characteristic, you will see 'Unknown' in the # HA frontend. - platform: ble_client ble_client_id: itag_black name: "Black iTag Battery" service_uuid: '180f' characteristic_uuid: '2a19' icon: 'mdi:battery' unit_of_measurement: '%'
The first thing enabled is the
esp32_ble_tracker component. This sets up
the BLE stack on the device and listens for available devices.
ble_client component will listen to devices discovered by
the tracker, and establish a connection to the given device when it is
binary_sensor provides a template sensor which will export to the
HA frontend the sensor that’s switched by the BLE tag’s button.
The first entry in the
sensor component is used to configure the specific
Service and Characteristic UUIDs for an iTag’s button. It also enables BLE
notifications and sets up an automation to toggle the
a notification is received from the tag. Automatic updates are disabled, there
is no point querying the tag for the device state, as we will be immediately
notified when the button is pressed.
sensor entry listens for a well-known Service and Chacteristic
that is used by many BLE devices to give battery level information. This sensor
will be exposed in the HA frontend to determine the state of the tag’s battery.
Note that many tags will not provide this service, so you will not see a valid
value. If not, you can remove this from the config.