Local Bluetooth presence/device tracking for Apple Watch, iPhone and iPad with security relevant unlocked property

DigiH · January 19, 2024, 10:23am

Hi all,

I wanted to inform you about our newly implemented feature with the recent release of Theengs Gateway to allow for fast local Bluetooth presence/device tracking for Apple Watch, iPhone and iPad, with additional unlocked property, to allow for security relevant automations, like opening gates, garage doors or even unlocking door locks etc., to only run if an authorised user is arriving back home, without the fear that these automations would also run in case the devices got lost or stolen.

The easiest and quickest installation for Home Assistant users is the Theengs Gateway Add-On

This also requires for the MQTT Integration to be installed.

Once installed, follow the instructions on how to retrieve the Identity Bluetooth MAC Address and Identity Resolving Key for your Apple devices, and enter them into the Theengs Gateway Add-On Configuration, as described in its Documentation, e. g.

{"00:11:22:33:44:55:66":"0dc540f3025b474b9ef1085e051b1add","AA:BB:CC:DD:EE:FF":"6385424e1b0341109942ad2a6bb42e58"}

With DISCOVERY turned on in the Add-On Configuration and having entered the above details, your discovered devices then show up in the MQTT Integration, from which they can be added to your dashboards, looking like

with any of the device trackers also available to be assigned to individuals.

While the Apple Watch continuously sends the unlocked state as long as its worn on the wrist of its owner and being unlocked with its Passcode, there are known restrictions for the unlocked state on iPhone and iPad

• An unlocked lock screen does not register as unlocked - iPhone users will know what this somehow contradictory unlocked lock screen is
• Unlocked for the iPhone and iPad really signifies fully unlocked device with recent user interaction, so after a certain time, also depending on the device’s auto-lock setting, even before a fully locked device the state will already switch back to locked.
• During a phone or Facetime call the state will be reported as locked. We are already looking into implementing phone/Facetime call detection for allowing incoming call alerts in a future update.

We hope this might be interesting to some of you. Any feedback is appreciated.

mandolin · February 25, 2024, 7:08pm

I must be missing something. I followed the instructions using my MQTT host, username, password, and port. The addon successfully started. So, then I added 2 of our iOS devices (my phone and watch) to the IDENTITIES.

At first I used the instructions from the post above (substituted my know MAC address and the Name from MacOS Keychain, without the dashes): {"00:11:22:33:44:55:66":"0dc540f3025b474b9ef1085e051b1add","AA:BB:CC:DD:EE:FF":"6385424e1b0341109942ad2a6bb42e58"}

That did not work, so I tried the configuration from here:
https://gateway.theengs.io/use/use.html#getting-identity-resolving-key-irk-for-apple-watch-iphone-and-ipad
using {"11:22:33:44:55:66": "WERknmckjn51464saa=="} and substituting my MAC address (same as above), but the Remote IRK key from the data section that resembles the “WER…”.

TheengsGateway saved this data, but the devices never appeared. So I tried to toggle GENERAL_PRESENCE and PRESENCE. The phone and watch still do not show up, either in MQTT devices or in MQTT Explorer.

In MQTT Explorer, I can see the topic home/TheengsGateway/BTtoMQTT/ and other BLE devices (some Govee lights), but NOT my phone or watch.

What am I doing wrong?

Also, will I be able to track battery levels/charging, longitude/latitude for the IOS devices? I DO like that I could change the scan interval, but would like to do that more often for some devices and not others (like my husband’s).

DigiH · February 26, 2024, 2:01pm

Hi @mandolin

This looks like some wrong entries in the IDENTITIES section of your devices.

Did you make sure you got the Identity Bluetooth MAC addresses directly from Settings > General > About > Bluetooth on the actual device / in the Watch app?

And the IRK from the Keychain entry’s long text field section at the very end, with the entry like

    …
    </dict>
	<key>Remote IRK</key>
	<data>
	XXXXXXXXXXXXXXXXXXXXXX==
	</data>
</dict>
</plist>

XXXXXXXXXXXXXXXXXXXXXX== being the required IRK?

And do you have the latest Theengs Gateway Add-on installed with version 1.11.0?

TheengsGateway saved this data, but the devices never appeared. So I tried to toggle GENERAL_PRESENCE and PRESENCE

The only important setting for this really is DISCOVERY, which should be ON.

This is not possible with this implementation, which relies on local Bluetooth advertising broadcasts only. Because of that very fast and reliable, but not able to receive or decode any battery level or GPS location.

mandolin · February 27, 2024, 11:22am

It was the wrong MAC address, which I used from MacOS keychain with the IRK. I can see it in MQTT Explorer now. Unfortunately, I really wanted to track my Apple watch, so this is not the right HA component for me.

Thank you

DigiH · February 27, 2024, 5:25pm

Hi @mandolin

All you need is to enter the same Identity Bluetooth MAC and IRK for your Apple Watch.
Unless you want GPS tracking, for which you alternatively or additionally need some other implementation.

flave · March 6, 2024, 10:42pm

I got an error trying to start the add-on.

ERROR:BLEGateway:[org.freedesktop.DBus.Error.AccessDenied] An AppArmor policy prevents this sender from sending this message to this recipient; type="method_call", sender="(null)" (inactive) interface="org.freedesktop.DBus" member="AddMatch" error name="(unset)" requested_reply="0" destination="org.freedesktop.DBus" (bus)

any idea how to fix that?

DigiH · March 7, 2024, 6:10pm

Hi @flave

Did you have a look at your AppAmor policies, as this seems to be preventing the Theengs Gateway Add-on from running properly.

Also, have you tried completely uninstalling the Theengs Gateway Add-on and then installing it afresh?

emanuele.bordon · March 8, 2024, 10:58am

@DigiH
Finally, it’s just what I was looking for, and it finally makes me stop fighting with the native Bluetooth device tracker.

I want your advice on making it as fast and reliable as possible regarding Home/Away detection.

Again, thank you so much. It seems to work very, very well.

DigiH · March 8, 2024, 1:19pm

Hi @emanuele.bordon

You can set the responsiveness in the Add-on Configuration with the time between scans (TIME_BETWEEN) and the scan duration (SCAN_DUR) for recognising HOME, and then TRACKER_TIMEOUT in seconds after which time a tracker should be recognised as AWAY (defaults to 120 seconds.)

The default is 5 seconds for both TIME_BETWEEN and SCAN_DUR.

Personally I have TIME_BETWEEN 12 and SCAN_DUR 3 which will issue a 3 seconds scan every 12 seconds, making sure I have an updated status every 15 seconds for HOME and 180 for AWAY after 3 minutes.

You’re welcome, glad to hear you are enjoying this implementation

e-raser · April 11, 2024, 4:47pm

I don‘t have a Mac. How to get the key?
Is this feature limited to TheengsGateway or can we also use this with OMGs? (as I have several of them around placed in strategic suitable locations, while the TheengsGateway on the HA server (addon) won‘t help me much for detecting my iDevices)

DigiH · April 11, 2024, 5:27pm

While I do not have any personal experience with these alternative options, there is a whole guide thread here on the forum

Depending on how you get your IRK it might be in HEX format, you will have to convert it into base64 for usage with Theengs Gateway.

Currently this is limited to Theengs Gateway, but might also be added to OpenMQTTGateway in the future.

I think I might have mentioned this to you before with your BM2, you can either install the esp32dev-ble-mqtt-undecoded binary on all your ESP32s so that they all function as remote Bluetooth reception antennas only, forwarding the undecoded messages to a central Theengs Gateway which does all the decoding, including this Apple devices implementation, or you can just convert your exiting OMGs by publishing
{"extDecoderEnable":true,"save":true}
to the
home/OpenMQTTGateway/commands/MQTTtoBT/config
topic.

By using one or more undecoded OpenMQTTGateway gateways like that you can make sure to have a reliable coverage over a wide area.

Vahaldor · March 3, 2025, 2:31pm

I am trying to install Theengs but it stucks in the installation process, circle still rotating, nothing happens next.

Vahaldor · March 3, 2025, 2:57pm

To all others, this ADDON completely CRASHED my home assistant VM. It even does not boot up. See here:

syngin · March 9, 2025, 5:39pm

This sounds like a really perfect solution but unfortunately I am not able to get it working. I installed the TheengsGateway addon, got the MAC addresses from my iPhone and Apple Watch and both IRK keys from my Macs keychain. Added it to the TheengsGateway identity config field like this {“111”:“xxx”,“222”.“yyy”}

One thing that confuses me is this log entry from TheengsGateway:

ERROR:BLEGateway:No Bluetooth adapters found.

I have a ESPhome Bluetooth Proxy device which is working fine for some other connected devices like a BT humidity sensor. I have no BT dongle device connected directly which is why I am getting the mentioned error from above.

I think that I am missing something.
Do I have to add an MQTT config to my ESPhome bt proxy like this to have it available for TheengsGateway?

mqtt:
  broker: 10.0.0.2
  username: livingroom
  password: !secret mqtt_password

This page says no or I don’t understand it well.

Has someone got it working with a similar setup like mine?
Is this even possible?

DigiH · March 9, 2025, 8:31pm

Hi @syngin

This is the issue you are seeing, as ESPhome Bluetooth Proxies are not compatible with Theengs Gateway, the same as they are not compatible with the HA ble-monitor and other non-ESPHome implementations, and if you do not have a local BT on your machine running Home Assiatnt currently the Theengs Gateway Add-on is just not able to pick up any Bluetooth broadcasts at all, even if your iPhone and Apple Watch Identity MACs and IRKs are correctly entered.

You can use an ESP32 as a remote proxy BT receiver though if you install the esp32dev-ble-mqtt-undecoded binary of OpenMQTTGateway on it. Then the Theengs Gateway Add-on will automatically pick it up as a proxy and things should work for you as expected.

Depending on which BT humidity sensor you are currently using the ESPhome Bluetooth Proxy for, it might also be picked up by Theengs gateway once you give it Bluetooth access.

I hope this clarifies things a bit more.

syngin · March 11, 2025, 7:04pm

Hi @DigiH

Wow, you really brought light into the dark! I am using an Olimex ESP32-POE-ISO-EA-IND. Do you think it will also work with esp32-olimex-gtw-ble-poe-iso firmware or must it be the undecoded version? Unfortunately there is no other undecoded version for my Olimex device.

Btw I am using the compatible SwitchBot Outdoor Meter and SwitchBot Bot devices.

DigiH · March 11, 2025, 9:57pm

Hi @syngin

No problem, you can either install any of the applicable Olimex binaries, depending on if you just want a quick web install or if you want to upload through PlatformIO.

The option to have any BLE gateway transmit raw undecoded BLE MQTT messages - which will then automatically be picked up by the Theengs Gateway Add-on for decoding - can be turned on for any BLE gateway at runtime, with

home/YOURGATEWAYNAME/commands/MQTTtoBT/config -m '{"extDecoderEnable":true, "save":true}'

Settable through MQTT Explorer, the gateway’s WebUI or any other MQTT publishing means.

The pre-built undecoded ESP32 binary is just a quick shortcut upload for the very widespread ESP32 dev kits .

syngin · March 13, 2025, 8:58pm

@DigiH
So, it’s working fine so far with your guidance. My iPhone and Apple Watch have been discoverd in MQTT Explorer but I can’t find them in HA. TheengsGateway also catched up the data from what I can see with MQTT Explorer. Do I have to set here (My Olimex Theengs OpenMQTTGateway) something too?

Btw my SwitchBot devices are working!

DigiH · March 16, 2025, 6:12pm

@syngin

Nothing to do on the ESP32 gateway, but make sure that Auto Discovery is turned on in the Theengs gateway setting.

Then you should see your iPhone, Apple Watch and SwitchBots in the MQTT Integration’s devices list, from where you can add them to your dashboards.

syngin · March 17, 2025, 6:46pm

@DigiH

In MQTT Explorer I can clearly see my iPhone and Apple Watch but in the TheengsGateway log it will not appear and also not in HA MQTT integration. Please can you have a look at my config?

MQTT_HOST: localhost
MQTT_USERNAME: ***
MQTT_PASSWORD: ***
MQTT_PORT: 1883
MQTT_PUB_TOPIC: home/TheengsGateway/BTtoMQTT
MQTT_SUB_TOPIC: home/+/BTtoMQTT/undecoded
MQTT_PRE_TOPIC: home/presence/TheengsGateway
PRESENCE: true
GENERAL_PRESENCE: true
PUBLISH_ALL: true
PUBLISH_ADVDATA: false
BLE: true
SCAN_DUR: 10
TIME_BETWEEN: 60
TRACKER_TIMEOUT: 120
LOG_LEVEL: INFO
LWT_TOPIC: home/TheengsGateway/LWT
DISCOVERY: true
DISCOVERY_TOPIC: homeassistant
DISCOVERY_DEVICE_NAME: TheengsGateway
DISCOVERY_FILTER: ""
HASS_DISCOVERY: true
SCANNING_MODE: active
TIME_SYNC: "[]"
TIME_FORMAT: false
TLS_INSECURE: false
ENABLE_TLS: false
ENABLE_WEBSOCKET: false
IDENTITIES: >-
  {"XX:XX:XX:XX:XX:XX":"***************************","YY:YY:YY:YY:YY:YY":"***************************"}
BINDKEYS: ""
BLACKLIST: ""
WHITELIST: ""

Example log. No iPhone or Apple Watch but a lot of other stuff from my neighbours.

[19:40:32] INFO: Creating TheengsGateway configuration...
[19:40:34] INFO: IDENTITIES: {XX:XX:XX:XX:XX:XX":"***************************","YY:YY:YY:YY:YY:YY":"***************************"}
[19:40:34] INFO: BINDKEYS: 
[19:40:34] INFO: BLACKLIST: 
[19:40:34] INFO: WHITELIST: 
[19:40:34] INFO: Starting TheengsGateway...
INFO:BLEGateway:Received `{"id":"*******************","rssi":-49}` from `home/OMG_ESP32_OLM_POE/BTtoMQTT/undecoded` topic
INFO:BLEGateway:Received `{"id":"*******************","rssi":-48}` from `home/OMG_ESP32_OLM_POE/BTtoMQTT/undecoded` topic
INFO:BLEGateway:Received `{"id":"*******************","name":"SomeDevice","rssi":-79}` from `home/OMG_ESP32_OLM_POE/BTtoMQTT/undecoded` topic