IRKey Explorer is a Home Assistant app that controls a permanent ESP32 enrollment node and collects Bluetooth Identity Resolving Keys (IRKs). The keys can be copied into Home Assistant's Private BLE Device integration or used by any compatible BLE presence system.
The ESP32 runs the current ESPresense firmware. IRKey Explorer connects to it through the Home Assistant MQTT broker and provides a focused Ingress dashboard for enrollment, telemetry, captured keys, and device management.
- Discover ESPresense nodes automatically through MQTT.
- Display node connectivity, IP address, firmware, Wi-Fi RSSI, uptime, memory, and fingerprint count.
- Start or cancel a two-minute BLE enrollment window.
- Capture IRKs from iPhone, iPad, Apple Watch, and other compatible bonded devices when ESPresense publishes an IRK.
- Display complete IRKs with one-click copy controls.
- Retain a local enrollment history in Home Assistant app backups.
- Restart the enrollment ESP32 and remove retained enrollments.
- Open Home Assistant's Private BLE Device setup directly from the dashboard.
- Work with Bermuda, ESPresense, and other systems that resolve BLE private addresses from an IRK.
This project was designed around the MH-ET LIVE ESP32 MiniKit / ESP32 D1 Mini. The seller description sometimes mentions ESP8266; verify that the module and metal RF can are marked ESP32. An ESP8266 has no Bluetooth and cannot perform IRK enrollment.
You need:
- One ESP32 D1 Mini board.
- A data-capable Micro-USB cable for flashing.
- A stable 5 V USB power supply for permanent operation.
- A computer running Chrome, Edge, or another Chromium browser with WebSerial.
- A 2.4 GHz Wi-Fi network reachable by Home Assistant and MQTT.
- Home Assistant with the Mosquitto broker app and MQTT integration configured.
No GPIO wiring or soldering is required. Leave the ESP32 antenna end clear of metal, large power supplies, and enclosed wiring. Place the finished node where the phone or watch can be brought within a few feet during enrollment.
- Connect the ESP32 D1 Mini to your computer with the data-capable USB cable.
- Open the official ESPresense firmware installer in Chrome or Edge. Firefox and Safari do not support the required WebSerial flow.
- Select Connect and choose the new serial/COM port belonging to the ESP32.
- Allow the installer to detect the ESP32 and select the current stable build.
- Select Install ESPresense and wait for flashing and verification to finish.
- Disconnect and reconnect power if the board does not reboot automatically.
If no serial port appears, try another cable and close Arduino IDE, PlatformIO, or any serial terminal that may already have the port open. Some D1 Mini clones also require the appropriate CH340 or CP210x USB serial driver.
After flashing, the board broadcasts an open Wi-Fi network beginning with
ESPresense-.
- Join the
ESPresense-...network from a phone or computer. - Wait for the captive portal or open
http://192.168.4.1manually. - Configure these values:
| ESPresense field | Recommended value |
|---|---|
| Room name | IRK Enrollment |
| Wi-Fi SSID | Your trusted 2.4 GHz network |
| Wi-Fi password | The network password |
| MQTT server | Home Assistant's LAN IP address or resolvable hostname |
| MQTT port | 1883 |
| MQTT username | A Home Assistant/Mosquitto user |
| MQTT password | That user's password |
| Discovery topic prefix | homeassistant |
| Send telemetry | Enabled |
| Send discovery | Enabled |
- Save the configuration and let the ESP32 reboot.
- Reconnect your phone or computer to its normal Wi-Fi network.
- Leave the ESP32 powered permanently from its 5 V USB supply.
ESPresense currently sends MQTT credentials without TLS. Use it only on a trusted local network and use a dedicated credential rather than reusing an important password.
In Home Assistant, open Settings → Devices & services → MQTT. An ESPresense
device named IRK Enrollment should appear within about a minute.
For a lower-level check, open Configure → Listen to a topic, subscribe to:
espresense/rooms/irk-enrollment/#
The node should publish online under status and JSON under telemetry.
-
In Home Assistant, open Settings → Apps → App store.
-
Open the store menu and select Repositories.
-
Add this repository:
https://github.com/ComputerWhisperers/IRKey-Explorer -
Find and install IRKey Explorer.
-
Start the app and open its Web UI.
-
The Mosquitto connection is supplied automatically through Home Assistant's MQTT service discovery; no broker password is entered in this app.
-
Confirm the
IRK EnrollmentESP32 appears as Online in the node selector.
The app expects the standard espresense MQTT prefix. If ESPresense was
configured with another prefix, change MQTT topic prefix on the app's
Configuration tab and restart it.
- Select the online ESP32 in IRKey Explorer.
- Choose the device type, enter a friendly name, and select Start enrollment.
- On the Apple device, open Settings → Bluetooth.
- Select
ESPresenseand accept the secure pairing request. - The captured 32-character IRK appears in the dashboard.
- Start enrollment from IRKey Explorer.
- On the watch, open Settings → Bluetooth.
- Wait for
ESPresenseto appear. Some watchOS versions list it under Health Devices because the ESP32 temporarily advertises as a heart-rate monitor. - Select
ESPresenseand accept pairing. - The captured Watch IRK appears separately in the dashboard.
Enrollment closes automatically after two minutes. If the ESPresense device does not appear, toggle Bluetooth on the Apple device and start enrollment again.
Samsung Galaxy phones and most Android phones rotate their BLE MAC addresses, but ESPresense does not normally receive an IRK from Android enrollment. The settled ESPresense Android path is to enable the Home Assistant Companion App BLE Transmitter sensor on the phone, which advertises a stable iBeacon-style UUID that Bermuda and ESPresense can use.
Galaxy watches vary by model and software. If a Galaxy Watch does not pair with
the ESPresense enrollment node and publish an irk:<32-hex> MQTT config, IRKey
Explorer cannot discover its IRK automatically.
- Keep the enrolled phone or watch nearby and broadcasting.
- Copy its IRK from IRKey Explorer.
- Open Settings → Devices & services → Add integration.
- Select Private BLE Device and paste the IRK.
- Complete validation while the device remains in Bluetooth range.
Bermuda automatically adds its room and distance sensors to devices registered through Private BLE Device. Other IRK-aware BLE systems can use the same key.
- ESP32 is absent from the app: Verify Mosquitto is running, the MQTT
integration is configured, and
espresense/rooms/irk-enrollment/statuscontainsonline. - ESP32 never joins Wi-Fi: The classic ESP32 uses 2.4 GHz Wi-Fi. Power-cycle it and reconnect to the captive portal to correct its network settings.
- MQTT authentication fails: Re-enter the MQTT username and password in the ESPresense Network page. Do not use a Home Assistant long-lived access token.
- No pairing target appears: Bring the device closer, cancel enrollment, toggle Bluetooth, and start a fresh two-minute window.
- IRK is captured but Private BLE validation fails: Keep the device awake and nearby until Home Assistant observes a matching rotating BLE address.
- Need firmware logs: Connect USB and use the official ESPresense serial terminal at 115200 baud.
An IRK allows rotating BLE addresses to be correlated with a specific device.
IRKey Explorer displays keys in full and stores them in /data/devices.json.
Protect Home Assistant access, MQTT access, and app backups accordingly.
The dashboard is exposed only through Home Assistant Ingress and does not open a standalone web port.
BLE enrollment and ESP32 firmware are provided by ESPresense. This project communicates with ESPresense through its documented MQTT topics and does not redistribute or modify its firmware.