將 Apple AirTag 接入 Home Assistant

1. 架構

整體流程：

AirTag
   ↓
Apple Find My Network
   ↓
Apple Find My Backend
   ↓
FindMy.py
   ↓
hass-FindMy
   ↓
Home Assistant
   ↓
device_tracker.xxx

主要使用兩個專案：

AirTag key 匯出：stek29/export-findmy
Home Assistant integration：malmeloo/hass-FindMy

底層 Find My library：

malmeloo/FindMy.py

2. 前置需求

需要：

Apple 原廠 AirTag
AirTag 已配對至自己的 Apple Account
一台 Mac
Home Assistant
HACS
Apple Account 已啟用 2FA

本流程已實際使用：

macOS 26 Tahoe
export-findmy
FindMy.py
hass-FindMy
Home Assistant

成功取得原廠 AirTag 的位置。

3. 在 Mac 安裝 export-findmy

首先安裝 protobuf：

brew install protobuf

確認 Rust 是否已安裝：

rustc --version
cargo --version

若沒有 Rust：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

下載 export-findmy：

git clone https://github.com/stek29/export-findmy.git
cd export-findmy

編譯：

cargo build --release

成功時會看到類似：

Finished `release` profile [optimized]

執行檔位於：

target/release/export-findmy

4. 建立 Device Profile

建立 local directory：

mkdir -p .local

複製範本：

cp device-profile.template.toml .local/device-profile.toml

此檔案會保存 exporter 使用的 persistent device UUID / UDID。

5. 登入 Apple Account 並取得 AirTag Keys

執行：

./target/release/export-findmy \
  --apple-id 'YOUR_APPLE_ID' \
  --device-profile .local/device-profile.toml

例如：

./target/release/export-findmy \
  --apple-id 'user@example.com' \
  --device-profile .local/device-profile.toml

程式會依序進行：

1. Connecting to anisette server
2. Authenticating Apple ID
3. Apple 2FA
4. Fetching MobileMe delegate
5. Setting up CloudKit & Keychain
6. Joining iCloud Keychain trust circle
7. Exporting Find My accessories

Apple 2FA

登入時可以選：

0 - Trusted Device
1 - SMS

選擇適合自己的驗證方式，輸入收到的 2FA Code。

6. 選擇 iCloud Keychain Escrow Bottle

程式會列出 Apple Account 中可使用的裝置，例如：

Found 3 escrow bottle(s):

[0] iPhone
[1] MacBook Pro
[2] Old MacBook Pro

Choose bottle [0]:

選擇一台自己知道解鎖密碼的裝置。

如果選擇：

iPhone

輸入該 iPhone 的螢幕解鎖密碼。

如果選擇：

Mac

輸入該 Mac 對應的登入密碼。

成功後 export-findmy 會從 iCloud Keychain / CloudKit 取得 Find My accessory 資料。

7. 取得 AirTag JSON

成功後會產生類似：

.local/keys/
├── My_AirTag_xxxxx.plist
└── My_AirTag_xxxxx.json

其中：

.json

可以直接供 FindMy.py / hass-FindMy 使用。

⚠️ 安全注意事項

JSON 內含 AirTag 的敏感 key material。

請：

不要上傳到 GitHub
不要貼到論壇
不要透過公開網址分享
建議保留一份安全備份

另外：

.local/auth_cache.plist

包含 Apple authentication/session 相關資料，也不應公開。

建議將：

.local/

加入 .gitignore。

8. Home Assistant 安裝 hass-FindMy

使用：

malmeloo/hass-FindMy

在 HACS 中加入 Custom Repository：

https://github.com/malmeloo/hass-FindMy

Repository Type：

Integration

下載並安裝：

FindMy

完成後重新啟動 Home Assistant。

9. 新增 FindMy Integration

進入：

Settings
→ Devices & services
→ Add Integration
→ FindMy

依照設定流程加入 Apple Account。

Apple Account 用來：

Home Assistant
      ↓
FindMy.py
      ↓
Apple Find My Backend
      ↓
下載 Location Reports

10. 匯入 AirTag JSON

接著在 FindMy integration 中新增 Tracker。

選擇前面 export-findmy 產生的：

My_AirTag_xxxxx.json

匯入成功後，Home Assistant 應該會產生：

device_tracker.findmy_xxxxx

例如：

device_tracker.findmy_school_bag

11. 確認 AirTag 是否正常定位

進入：

Developer Tools → States

搜尋：

device_tracker.findmy_xxxxx

正常取得 Find My report 後，應可看到 GPS 位置及相關 attributes。

例如：

source_type: gps
latitude: 25.xxxxx
longitude: 121.xxxxx
detected_at: 2026-08-31T...
status: ...
alignment_index: ...
alignment_date: ...
friendly_name: School Bag

其中最重要的是：

latitude
longitude
detected_at

12. 更新頻率

AirTag 並不是 GPS Tracker。

流程實際上是：

AirTag
   ↓ BLE
附近 Apple 裝置
   ↓
Apple Find My Network
   ↓
Find My location report
   ↓
FindMy.py
   ↓
Home Assistant

因此即使 Home Assistant 查詢 Apple，也不代表一定會取得一筆新的位置。

hass-FindMy 預設會限制 Apple Account 的查詢頻率，通常約：

15 分鐘 / Apple Account

不建議為了追求即時更新而過度提高查詢頻率。

AirTag 比較適合：

小孩書包
鑰匙
車輛最後位置
行李
腳踏車
不要求即時更新的物品追蹤

不適合拿來做秒級或分鐘級即時 GPS tracking。

13. detected_at 很重要

Home Assistant 更新 entity 的時間與 AirTag 真正被 Find My Network 定位的時間並不相同。

例如：

AirTag 最後被偵測：14:42
HA 向 Apple 查詢：14:55

此時真正的位置時間應該看：

detected_at = 14:42

而不是 HA 的：

last_updated = 14:55

因此建立 Dashboard 或 Automation 時，建議同時顯示：

📍 AirTag：學校
🕐 最後定位：13 分鐘前

而不是只顯示：

📍 AirTag：學校

14. 常見問題

Entity 出現，但沒有位置

例如：

tracking_type: position
source_type: gps
detected_at: null
status: null
alignment_index: 56148
alignment_date: ...

這代表 accessory 已成功加入，但目前尚未取得可用的 location report。

先等待至少一個 polling interval，再確認：

detected_at
latitude
longitude

是否出現。

15. 更新或重建 Home Assistant

建議另外安全備份：

AirTag JSON

AirTag JSON 並不是一般 Apple login session，因此正常情況下不會每隔幾天或幾個月失效。

通常只要：

AirTag
   ↓
仍維持原本 Apple Account 配對

原本匯出的 accessory JSON 就可以繼續使用。

可能需要重新取得 key 的情況包括：

AirTag 被移除後重新配對
AirTag 被 reset 並重新建立配對
Apple 未來修改 Find My protocol/key mechanism

單純：

更換 AirTag 電池
Home Assistant 更新
Proxmox 重開
iPhone 更新
macOS 更新

通常不需要重新 export AirTag JSON。

Apple Account authentication/session 則是另一回事，未來可能需要重新驗證。

參考專案

export-findmy

https://github.com/stek29/export-findmy

FindMy.py

https://github.com/malmeloo/FindMy.py

hass-FindMy

https://github.com/malmeloo/hass-FindMy

最終結果

完成後：

Apple AirTag
     ↓
Find My Network
     ↓
FindMy.py
     ↓
hass-FindMy
     ↓
Home Assistant
     ↓
device_tracker.findmy_xxxxx

之後即可使用 Home Assistant 的：

Map
Zones
Automations
Dashboards
History

來處理 AirTag 的位置資訊。

資訊文件 home assistant MAC AirTag