Connect Home Assistant, an ESP32 scale or a Python script to a TigerTag account.
This repository documents how any client signs in with the user's own TigerTag credentials, reads their filament spools and racks in Firestore, and writes spool weights back. What is documented here is what is deployed, and every change to it is recorded in the changelog.
users/{uid}/inventoryEvery client follows the same four steps: fetch the public Firebase config, sign in as the user, call the Firestore REST API with the user's token, and keep that token fresh.
One GET returns the Firebase project config. The apiKey is public by design: it identifies the project, not the caller. Cache it; a weekly refresh is enough.
01-firebase-config.mdThe user's own email and password return a UID, a 1-hour idToken and a refreshToken. Google Sign-In needs a browser, so headless clients use a password.
02-authentication.mdSend the idToken as a Bearer token. Spools live in users/{uid}/inventory, racks in users/{uid}/racks; weights are net grams, dates Unix milliseconds.
03-data-model.mdRefresh the idToken before the hour is up and replace both stored tokens. On a permission-denied, refresh once and retry the read once.
Refreshing the idTokenGET 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}The values in braces come from the previous call: apiKey and projectId from the config, uid and idToken from the sign-in.
Each guide in docs/clients covers authentication, the data it reads or writes, the field mapping and the code. The snippets below are copied from the guides.
A Home Assistant custom component that exposes one sensor per spool, with the remaining weight in grams as its state. The guide also covers friends' inventories, pagination and token storage; the config flow and sensor are skeletons, and a fully runnable component is still to be written.
{
"domain": "tigertag",
"name": "TigerTag",
"version": "0.1.0",
"requirements": ["pyrebase4>=4.5.0"],
"config_flow": true,
"iot_class": "cloud_polling"
}For a scale or NFC device: look up a spool by the scanned RFID UID (uid, then twin_uid), compute the net weight and write weight_available and last_update with an update mask. The guide ends with a complete ESP32 sketch (WiFi, ArduinoJson).
weight_available = max(0, measured_raw_weight - container_weight)A minimal Python client built on Pyrebase4: it signs in, lists your spools and prints how many spools each friend has. The guide holds the whole script and a sample run.
pip install -r requirements.txt
python tigertag_client.pyA one-way bridge from TigerTag to a Spoolman instance: brands become vendors, each brand, material and colour becomes a filament, and each inventory document becomes a spool, upserted through Spoolman's REST API. Run it from cron, systemd or Docker.
pip install -r requirements.txt
export TIGERTAG_EMAIL=you@example.com
export TIGERTAG_PASSWORD=yourpassword
export SPOOLMAN_URL=http://192.168.1.10:7912
export DRY_RUN=1 # dry-run mode
python3 sync.pyThe contract a TigerScale or compatible scale follows to appear online in Tiger Studio Manager and the TigerTag mobile app: a heartbeat document every 30 seconds, a weight update on every stable reading, and twin tags written in one atomic batch.
users/{uid}/scales/{mac} ← heartbeat, every 30 s
users/{uid}/inventory/{spoolId} ← weight_available + last_updateBuilding for another platform? A new guide goes in docs/clients, an optional runnable example in examples/. CONTRIBUTING.md
There is no shared key to protect and no master token to leak: a client can do exactly what its user can do, and Firestore enforces it on the server.
Every client signs in with the end user's own credentials. Never ship the firebase-admin SDK or any admin key in a third-party client.
Firestore Security Rules check every request against request.auth.uid: owners read and write their own documents, friends may read inventory and racks, and anything not allowed is denied. The public copy of the rules is in rules/firestore.rules.
Accepting a friend request writes a document on each side. While users/{friend}/friends/{you} exists you may read that friend's inventory and racks, read-only; deleting it cuts access immediately.
04-friend-system.mdPoll every 5 minutes at most often, never under 30 seconds, write only when a value changes, and pass a limit on list reads (200 spools, 50 racks). Firebase App Check is not enforced.
05-rate-limiting.mdThe repository is treated as a public contract: changes that affect clients reach this repository in the same release, and the changelog records each one as Added, Changed, Deprecated, Removed, Fixed or Security.
The core documents every integration builds on, in the order a client needs them.
This guide covers the cloud account. The chips, the apps and the SDKs have their own repositories.
The open NFC chip format for filament spools and resin bottles, its specification and the reference database.
OpenThe desktop app (Electron) that manages the same inventory; the documentation is verified against its releases.
RepositoryRead, verify, create and patch TigerTag chips offline, in JavaScript or Python, under Apache-2.0.
No. Every client signs in with the end user's own TigerTag email and password, and Firestore Security Rules decide what that user may read or write. There is no shared admin key, and the firebase-admin SDK must never be used in a third-party client.
The apiKey identifies the TigerTag Firebase project, not the caller. Without a valid idToken, obtained by signing in as a real user, it gives access to nothing; access control is done by authentication and by the Security Rules.
Not directly: Google Sign-In needs a browser redirect. A user who has only ever used Google sets a password on the account first, through the desktop or mobile app's forgot-password flow, and then signs in with email and password.
Every 5 minutes at most often for a sensor, every 15 minutes for a rack overview, and never under 30 seconds. A scale writes only when a weight changes. List reads should pass a limit: 200 for inventory, 50 for racks.
Yes, read-only. When two users are friends, each has a document for the other under users/{uid}/friends, and the rules let a friend read the inventory and racks. Either user can remove the friendship at any time, which cuts access immediately.
The documentation wins: a difference means a regression shipped. Open an issue on the repository with the page, the path you read or wrote and the response, with tokens and private keys removed.
The Security Rules and every code snippet in the documentation are under Apache-2.0, and attribution is waived for snippets pasted into your own project. The documentation itself is under CC-BY-4.0. The TigerTag name, logo and service are not covered by these licences.
Pick the guide for your platform in the README's quick links, and follow it from sign-in to your first read.