Referentie voor integraties van derdenTigerTagFirebase Integration
Verbind Home Assistant, een ESP32-weegschaal of een Python-script met een TigerTag-account.
Deze repository beschrijft hoe elke client inlogt met de eigen TigerTag-inloggegevens van de gebruiker, diens filamentspoelen en rekken in Firestore leest en spoelgewichten terugschrijft. Wat hier gedocumenteerd is, is wat er draait, en elke wijziging daarin wordt vastgelegd in de changelog.
Firebase AuthenticationHet eigen account van de gebruiker, een idToken van 1 uur
Authorization: Bearer {idToken}
Firestore Security RulesEigenaars lezen en schrijven, vrienden lezen
Firestoreusers/{uid}/inventory
0.1.3Nieuwste uitgebrachte versie van het contract (CHANGELOG, 2 mei 2026)
1 hGeldigheidsduur van een idToken: vernieuw het voordat het verloopt
5 minAanbevolen minimale polling-interval
3 maandenMinimale aankondigingstermijn voordat een veld wordt hernoemd of verwijderd
Hoe een client verbinding maakt met TigerTag
Elke client volgt dezelfde vier stappen: de openbare Firebase-configuratie ophalen, inloggen als de gebruiker, de Firestore REST API aanroepen met het token van de gebruiker, en dat token geldig houden.
1
Haal de openbare configuratie op
Eén GET geeft de configuratie van het Firebase-project terug. De apiKey is bewust openbaar: hij identificeert het project, niet de aanroeper. Sla hem in de cache op; wekelijks vernieuwen is genoeg.
Het eigen e-mailadres en wachtwoord van de gebruiker leveren een UID, een idToken van 1 uur en een refreshToken op. Google Sign-In heeft een browser nodig, dus headless clients gebruiken een wachtwoord.
Stuur het idToken mee als Bearer-token. Spoelen staan in users/{uid}/inventory, rekken in users/{uid}/racks; gewichten zijn netto grammen, datums Unix-milliseconden.
Vernieuw het idToken voordat het uur om is en vervang beide opgeslagen tokens. Bij een permission-denied vernieuw je één keer en probeer je de leesactie één keer opnieuw.
GET https://tigertag-cdn.web.app/__/firebase/init.json
POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={apiKey}
{ "email": "user@example.com", "password": "…", "returnSecureToken": true }
GET https://firestore.googleapis.com/v1/projects/{projectId}/databases/(default)/documents/users/{uid}/inventory
Authorization: Bearer {idToken}
De waarden tussen accolades komen uit de vorige aanroep: apiKey en projectId uit de configuratie, uid en idToken uit het inloggen.
Integraties die in deze repository zijn gedocumenteerd
Elke handleiding in docs/clients behandelt de authenticatie, de gegevens die worden gelezen of geschreven, de veldtoewijzing en de code. De fragmenten hieronder komen uit de handleidingen.
Schets van een component
Home Assistant
Een custom component voor Home Assistant die per spoel één sensor aanbiedt, met het resterende gewicht in grammen als status. De handleiding behandelt ook de inventarissen van vrienden, paginering en de opslag van tokens; de config flow en de sensor zijn skeletten, en een volledig werkend component moet nog worden geschreven.
Voor een weegschaal of NFC-apparaat: zoek een spoel op aan de hand van de gescande RFID-UID (uid, daarna twin_uid), bereken het nettogewicht en schrijf weight_available en last_update met een update mask. De handleiding eindigt met een volledige ESP32-sketch (WiFi, ArduinoJson).
Een minimale Python-client op basis van Pyrebase4: hij logt in, toont je spoelen en geeft weer hoeveel spoelen elke vriend heeft. De handleiding bevat het volledige script en een voorbeelduitvoer.
Een eenrichtingsbrug van TigerTag naar een Spoolman-instantie: merken worden leveranciers, elke combinatie van merk, materiaal en kleur wordt een filament, en elk inventarisdocument wordt een spoel, aangemaakt of bijgewerkt via de REST API van Spoolman. Draai het vanuit cron, systemd of Docker.
Het contract dat een TigerScale of compatibele weegschaal volgt om online te verschijnen in Tiger Studio Manager en de mobiele TigerTag-app: elke 30 seconden een heartbeat-document, een gewichtsupdate bij elke stabiele meting, en twin-tags die in één atomaire batch worden geschreven.
users/{uid}/scales/{mac} ← heartbeat, every 30 s
users/{uid}/inventory/{spoolId} ← weight_available + last_update
Bouw je voor een ander platform? Een nieuwe handleiding hoort in docs/clients, een optioneel werkend voorbeeld in examples/. CONTRIBUTING.md
Het account van de gebruiker, de regels van de gebruiker
Er is geen gedeelde sleutel om te beschermen en geen mastertoken dat kan uitlekken: een client kan precies wat zijn gebruiker kan, en Firestore dwingt dat af op de server.
Geen serviceaccount
Elke client logt in met de eigen inloggegevens van de eindgebruiker. Lever de firebase-admin SDK of een beheerderssleutel nooit mee in een client van derden.
Security Rules beslissen
Firestore Security Rules controleren elk verzoek aan de hand van request.auth.uid: eigenaars lezen en schrijven hun eigen documenten, vrienden mogen de inventaris en rekken lezen, en alles wat niet is toegestaan wordt geweigerd. De openbare kopie van de regels staat in rules/firestore.rules.
Eén band per vriendschap
Het accepteren van een vriendschapsverzoek schrijft aan beide kanten een document. Zolang users/{friend}/friends/{you} bestaat, mag je de inventaris en rekken van die vriend lezen, alleen-lezen; het verwijderen ervan beëindigt de toegang onmiddellijk.
Poll hooguit elke 5 minuten, nooit vaker dan elke 30 seconden, schrijf alleen als een waarde verandert, en geef een limiet mee bij het lezen van lijsten (200 spoelen, 50 rekken). Firebase App Check wordt niet afgedwongen.
De repository wordt behandeld als een openbaar contract: wijzigingen die clients raken komen in dezelfde release in deze repository terecht, en de changelog legt elke wijziging vast als Added, Changed, Deprecated, Removed, Fixed of Security.
Verandert niet zonder aankondiging
Documentpaden zoals users/{uid}/inventory/{spoolId}, users/{uid}/racks/{rackId} en users/{uid}/friends/{friendUid}.
De naam en betekenis van elk gedocumenteerd veld: weight_available is netto grammen, last_update is Unix-milliseconden, deleted: true betekent soft-deleted.
Het toegangsmodel voor vrienden, en de Firebase Auth-endpoints waarmee een client inlogt.
De apiKey en projectId, tenzij het hele project verhuist, wat minstens 6 maanden van tevoren wordt aangekondigd.
Kan veranderen: programmeer defensief
Referentietabellen krijgen nieuwe merken en materialen; numerieke id's worden alleen toegevoegd en nooit hergebruikt.
Handige HTTPS-endpoints op cdn.tigertag.io kunnen de vorm van hun verzoeken en antwoorden aanpassen.
Nieuwe collecties en nieuwe velden zijn altijd aanvullend: negeer de velden die je niet kent en blijf compatibel.
Heb ik een serviceaccount of een beheerderssleutel nodig?
Nee. Elke client logt in met het eigen TigerTag-e-mailadres en -wachtwoord van de eindgebruiker, en Firestore Security Rules bepalen wat die gebruiker mag lezen of schrijven. Er is geen gedeelde beheerderssleutel, en de firebase-admin SDK mag nooit in een client van derden worden gebruikt.
Waarom is de Firebase-apiKey openbaar?
De apiKey identificeert het Firebase-project van TigerTag, niet de aanroeper. Zonder geldig idToken, verkregen door in te loggen als een echte gebruiker, geeft hij nergens toegang toe; de toegangscontrole gebeurt via authenticatie en de Security Rules.
Kan Home Assistant of een ESP32 inloggen met Google?
Niet rechtstreeks: Google Sign-In vereist een doorverwijzing in de browser. Een gebruiker die altijd alleen Google heeft gebruikt, stelt eerst een wachtwoord in voor het account via de wachtwoord-vergeten-functie van de desktop- of mobiele app, en logt daarna in met e-mail en wachtwoord.
Hoe vaak mag mijn integratie pollen?
Hooguit elke 5 minuten voor een sensor, elke 15 minuten voor een overzicht van rekken, en nooit vaker dan elke 30 seconden. Een weegschaal schrijft alleen als een gewicht verandert. Bij het lezen van lijsten hoort een limiet: 200 voor de inventaris, 50 voor rekken.
Kan mijn integratie de spoelen van een vriend lezen?
Ja, alleen-lezen. Als twee gebruikers vrienden zijn, heeft elk van hen een document voor de ander onder users/{uid}/friends, en de regels laten een vriend de inventaris en rekken lezen. Elk van beide gebruikers kan de vriendschap op elk moment beëindigen, wat de toegang onmiddellijk afsluit.
Wat als de productie afwijkt van deze documentatie?
De documentatie heeft voorrang: een verschil betekent dat er een regressie is uitgerold. Open een issue in de repository met de pagina, het pad dat je las of schreef en het antwoord, met tokens en privésleutels verwijderd.
Onder welke licentie mag ik de code hergebruiken?
De Security Rules en elk codefragment in de documentatie vallen onder Apache-2.0, en naamsvermelding is niet vereist voor fragmenten die je in je eigen project plakt. De documentatie zelf valt onder CC-BY-4.0. De naam, het logo en de dienst TigerTag vallen niet onder deze licenties.
Begin je integratie
Kies de handleiding voor jouw platform in de snelkoppelingen van de README, en volg die van het inloggen tot je eerste leesactie.
