Source: docs/index.md
HerdTag documentation
HerdTag is an early-stage virtual-fencing ear tag for cattle. A small GPS + LoRa tag on the ear knows where the pasture boundary is, and plays a sound cue when the animal walks toward it. The tag makes that decision itself. A farm gateway relays positions to a backend, which shows the herd on a map and pushes new fence shapes back down to the tags.
The open question the project exists to answer is behavioural, not technical: will cattle reliably learn to respond to an ear-tag cue? The software is built so that question can be tested cheaply and safely. See PLAN.md for the roadmap and its go/no-go checkpoints.
Doc map
| Doc | Read it if you want to… |
|---|---|
| Architecture | understand the pieces and how data moves between them |
| Controller | know exactly when the tag cues, samples GPS, and declares a breach |
| Protocol | decode or produce the over-the-air bytes |
| Backend | run the server, call its API, connect The Things Stack |
| Simulation | run the offline herd simulator or the live virtual-tag demo |
| Firmware | build, test, or flash the tag code |
| Operations | run tags on a real farm: add, replace, re-fence, respond to alerts |
| Glossary | look up LoRaWAN, FSB2, h_acc, FTO and friends |
Hardware (parts list, pin map, enclosure, makerspace sessions) lives in hardware/BUILD.md.
Status
| Component | Where | State |
|---|---|---|
| Fence controller (reference) | src/herdtag/controller.py |
Built, unit-tested |
| Geometry, payload codecs, power model | src/herdtag/geo.py, protocol.py, power.py |
Built, unit-tested. Power numbers are placeholders until bench-measured |
| Herd simulator | src/herdtag/sim.py |
Built, smoke-tested. Cow response curves are guesses |
| Backend + map UI | src/herdtag/server/ |
Built, API-tested, and run end to end with virtual tags |
Virtual tags (herdtag demo) |
src/herdtag/demo.py |
Built, run end to end |
| C core (controller, geo, protocol) | firmware/core/ |
Built. Matches Python on 3,630 golden-vector checks |
| Tag sketch for RAK4631 | firmware/tag/ |
Written, syntax-checked only. Never compiled for the board or flashed |
| The Things Stack downlink push | src/herdtag/server/tts.py |
Written, untested against a live TTS |
| Hardware build | hardware/ |
Planned. Nothing bought or built yet. Enclosure never rendered |
| Cattle response | n/a | Unknown. This is what Phase 2 trials measure |
Quickstart
Everything below runs on a laptop with uv installed; no hardware is needed.
cd ~/herdtag
uv run pytest -q # Python tests
make -C firmware/core test # C core vs. golden vectors
uv run herdtag sim --cows 20 --days 2 # offline: compare cow-response models
To see the full system working with virtual tags, use two terminals:
uv run herdtag-server # terminal 1 → http://127.0.0.1:8000
uv run herdtag demo --speed 30 # terminal 2: 10 simulated cows with tags
Open http://127.0.0.1:8000. The demo creates a fence called "Demo pasture" in the Kansas Flint Hills and sends it to all ten tags. Within a few seconds every tag should show it as synced. Then the dots move, turn colour as they near the fence, and generate events.