Source: docs/backend.md

Backend

A FastAPI app (src/herdtag/server/) with SQLite storage. It has four jobs:

1. Take uplinks from The Things Stack (TTS) by webhook.
2. Store tag state, position history and events.
3. Manage fences and push them to tags as downlinks.
4. Serve the map UI, the dashboards and the analytics.

Running it

cd ~/herdtag
uv run herdtag-server                      # http://127.0.0.1:8000, DB file ./herdtag.db
HERDTAG_DB=/path/farm.db PORT=8080 HOST=0.0.0.0 uv run herdtag-server

With all three TTS_* variables set, fence assignments are pushed to TTS. Without them, the server works in local mode: downlinks go into a queue that only the virtual tags read, and the UI shows a banner saying so.

Endpoints

All bodies are JSON unless noted. Interactive OpenAPI docs are at /docs.

Ingest

POST /ingest/ttn: the TTS v3 uplink webhook.

• Body: the standard TTS uplink message. The fields used are end_device_ids.device_id, end_device_ids.dev_eui, received_at, uplink_message.f_port, uplink_message.frm_payload (base64), and uplink_message.rx_metadata[].rssi/snr (the strongest gateway is kept).
• Responses:
• {"ok":true,"state":"warning","events":[...],"cue":true} on success
• {"ignored":"not an uplink"} for joins, acks and other webhook types
• {"ignored":"unknown payload"} when the port isn't 1 or the payload isn't 11 bytes; this also logs an unknown_payload event
• 401 if the webhook secret is wrong

P=$(printf '16eb3159c673a873572101' | xxd -r -p | base64)
curl -s -X POST localhost:8000/ingest/ttn -H 'content-type: application/json' -d "{
  \"end_device_ids\": {\"device_id\": \"tag-01\", \"dev_eui\": \"70B3D57ED0000001\"},
  \"received_at\": \"2026-11-07T15:04:05.123456789Z\",
  \"uplink_message\": {\"f_port\": 1, \"frm_payload\": \"$P\", \"rx_metadata\": [{\"rssi\": -101, \"snr\": 4.5}]}}"
# {"ok":true,"state":"warning","events":[],"cue":true}

Events the backend derives from uplinks:

Tags and events

curl -s localhost:8000/api/tags
curl -s 'localhost:8000/api/tags/tag-01/track?hours=24'
curl -s 'localhost:8000/api/events?limit=20'

Fences

GET /api/fences lists the active (non-archived) fences: [{id, name, points:[[lat,lon],...], created_at, archived}].

POST /api/fences creates a fence. Responds 201 with the fence.

• Body: {"name": "North", "points": [[lat, lon], ...]}. A closing point equal to the first is dropped.
• Validation (422): 3–32 corners, valid lat/lon, no edges crossing each other, within ±32 km of its centre.
• Ids: fences get the lowest unused id from 1–255. The id is what tags report back.

curl -s -X POST localhost:8000/api/fences -H 'content-type: application/json' \
  -d '{"name":"North","points":[[38.4500,-96.5520],[38.4500,-96.5480],[38.4530,-96.5480],[38.4530,-96.5520]]}'
# {"id":1,"name":"North","points":[[38.45,-96.552],...],"created_at":...,"archived":0}

POST /api/fences/{id}/assign sends a fence to tags.

• Body: {"dev_ids": ["tag-01", "tag-02"]}, or {"dev_ids": null} for every known tag.
• For each tag it:
• sets assigned_fence
• marks older still-queued fence downlinks as superseded
• encodes the fence into fragments of at most 51 bytes
• pushes them to TTS if configured, otherwise queues them locally
• logs a fence_assigned event
• Response: [{dev_id, frames, status, detail}], where status is queued, sent_to_tts or error. A TTS failure for one tag doesn't stop the others.

curl -s -X POST localhost:8000/api/fences/1/assign -H 'content-type: application/json' -d '{"dev_ids":["tag-01"]}'
# [{"dev_id":"tag-01","frames":1,"status":"queued","detail":""}]

DELETE /api/fences/{id} archives a fence. It returns 409 if any tag is still assigned to it. Archived fences keep their id, so ids aren't reused.

Dashboards and analytics

The analytics only use what tags actually send. Anything they can't know (cue bursts per uplink, turn timestamps, accelerometer activity, gateway id, sound level) comes back in a gaps object, rather than being estimated.

Development only

POST /dev/downlinks/{dev_id}/take returns [{f_port, frm_payload}] for that tag's queued downlinks and marks them delivered_local. The virtual tags in herdtag demo call it right after each uplink, to mimic Class A. It has no auth, so don't expose it publicly.

Database schema

SQLite, created on start-up (server/db.py).

Times are Unix seconds (float, UTC). Uplink times come from TTS's received_at, not the server clock.

Connecting The Things Stack

The gateway and device registration steps are in hardware/BUILD.md §7. On the backend side:

1. Make the server reachable over HTTPS, for example with a Cloudflare Tunnel or a small VPS behind a reverse proxy.
2. In the TTS console, go to Application → Integrations → Webhooks → add a custom webhook: - Format JSON, base URL https://<host>, and enable Uplink message with path /ingest/ttn. - Add a header X-Webhook-Secret: <random string>, and start the server with the same HERDTAG_WEBHOOK_SECRET.
3. Create an API key in the application with permission to write downlink application traffic. Start the server with TTS_BASE, TTS_APP_ID and TTS_API_KEY.

Downlink push calls POST {TTS_BASE}/api/v3/as/applications/{app}/devices/{dev}/down/push. It sends one confirmed f_port: 2 entry per fragment, with a Bearer token. This path hasn't been tested against a live TTS yet. Check it against your TTS version's API reference on the first real run.

Security caveats

• No user authentication. Anyone who can reach the server can read positions, create and assign fences, and drain the local downlink queue. Keep it on 127.0.0.1, or put it behind an authenticating proxy (e.g. Cloudflare Access).
• The webhook secret protects only /ingest/ttn, and only when HERDTAG_WEBHOOK_SECRET is set.
• /dev/downlinks/* exists for the demo. It should be disabled or protected before any internet-facing deployment.
• Positions of animals on a named farm are sensitive. Treat the DB file and the CSV exports accordingly.