Własna integracja dla Samsung Galaxy SmartTag (gen 1, SmartTag+ i SmartTag2). Cel: z tagów, które we wbudowanej integracji SmartThings nie mają żadnych encji, zrobić w HA obecność, baterię i (opcjonalnie) położenie GPS.
Status: wczesny etap. Na
mainjest research, biblioteka (parser BLE, pula privacy ID, parser API) z testami i skrypt PoC. Integracja HA powstaje na gałęziach z PR.
Integracja SmartThings w HA nie tworzy encji dla tagów celowo: API SmartThings
zwraca dla tagów same null (także lokalizację), więc od 2025 r. HA dodaje tylko
urządzenie. Szczegóły i źródła: docs/RESEARCH.md.
Trzy niezależne źródła danych, każde opcjonalne:
- Chmura SmartThings, oficjalnie (PAT/OAuth). Z opisu urządzenia (
bleD2D): bateria, z którym telefonem tag był ostatnio połączony,nearby, czas ostatniego kontaktu. Z tego samego miejsca pochodzi materiał do puli privacy ID. - Lokalnie przez Bluetooth (główna wartość). HA Bluetooth / proxy ESPHome
słucha ramek
0xFD5A. Każdą ramkę dopasowujemy do konkretnego tagu przez pulę privacy ID wygenerowaną z danych z punktu 1. Efekt: obecność per tag, RSSI, najbliższe proxy (pokój), stan tagu (przy właścicielu / zgubiony), bateria i ruch. Bez odpytywania chmury, działa na rotujących MAC. - GPS z Samsung Find (nieoficjalnie, opcja). Proxy SmartApp FME
(
/trackers/geolocation) wymaga logowania kontem Samsung, nie PAT. Na dziś najlepiej działa gotowa integracja PixelShober/HA-SmartThings-Find. Rekomendacja: używać jej równolegle, a własny moduł GPS robić dopiero, gdy będzie potrzebny.
Przyciski tagu: obejście przez wirtualny przełącznik w aplikacji SmartThings (opis w RESEARCH.md).
| Ścieżka | Co |
|---|---|
custom_components/smarttag/ble.py |
parser ramek FD5A |
custom_components/smarttag/privacy.py |
generowanie puli privacy ID |
custom_components/smarttag/cloud.py |
rozpoznawanie tagów i parsowanie bleD2D z API SmartThings |
tools/st_probe.py |
PoC: co API mówi o Twoich tagach |
tests/ |
testy pytest |
docs/RESEARCH.md |
research ze źródłami |
- Wygeneruj PAT na https://account.smartthings.com/tokens (zakresy: urządzenia
r:devices:*,l:devices, aplikacjer:installedapps,l:installedapps). - Na maszynie z dostępem do internetu:
python3 -m venv .venv && .venv/bin/pip install cryptography
export SMARTTHINGS_TOKEN=... # nie wklejaj tokenu do repo ani do czatu
.venv/bin/python tools/st_probe.py --poolSkrypt wypisze tagi, baterię, ostatnie połączenie i czy da się zbudować pulę
privacy ID. Nie wypisuje tokenu ani kluczy. --raw dumps/ zapisuje zredagowane
JSON-y (katalog dumps/ jest w .gitignore).
- Research i źródła
- Parser FD5A, pula privacy ID, parser
bleD2D, testy - PoC na PAT
- Weryfikacja na prawdziwych tagach: czy PAT dostaje
encryptionKey, czy ramki w stanie 4 niosą privacy ID z puli - Integracja HA: config flow (PAT), koordynator chmury, sensory baterii i ostatniego połączenia
- Integracja HA: nasłuch Bluetooth,
device_tracker/obecność per tag, RSSI, najbliższe proxy - Rozdzielenie gen 1 / gen 2 w modelu urządzenia
- (opcja) GPS przez Samsung Find, jeśli PixelShober przestanie wystarczać
- HACS:
hacs.json,manifest.json, walidacja hassfest/HACS w CI
Część wiedzy pochodzi z inżynierii wstecznej (uTag, praca USENIX). Samsung może to
zmienić bez ostrzeżenia. Używaj tylko z własnymi tagami. Sekrety (PAT,
encryptionKey) trzymaj wyłącznie w magazynie HA lub zmiennych środowiskowych.
MIT