tsOS-vhf is a Raspberry Pi OS image for unattended VHF wildlife-tracking stations. It receives signals from VHF tags on animals, records detections and features, and forwards them for bearing estimation and activity classification.
trackIT Systems supplies vhf:tracker stations commercially, running this image in the field.
The image is built on tsOS-base for arm64 (Raspberry Pi 3+ / Compute Module).
On top of tsOS-base:
- pyradiotracking — RTL-SDR signal detection, matching, CSV/MQTT export
- librtlsdr fork (installed from its release packages) and pyrtlsdr — R802T gain stages and Python bindings
radiotracking.service— runs aspiin a systemd sandbox, starts after time sync,Nice=-10, writes detections to/data
Inherited from tsOS-base: tsconfig, FileBrowser Quantum, Mosquitto, tstelemetry, Chrony/gpsd, tslocation, WittyPi (tsschedule), WireGuard, LTE helpers, overlayroot.
This release line is built on tsOS-base 2027.0.10 and changes the root/pi privilege model. Devices on earlier images have to be reflashed; no delta update is published into it.
Images are published in GitHub Releases. Release notes live in CHANGELOG.md.
Flash with Raspberry Pi Imager or dd. Default hostname is tsos-default-name, which names the station tsos-vhf-<serial> at boot (set systemd.hostname= in cmdline.txt on the boot partition). For backend matching, use <planner>-<project>-<number>; each station name must be unique.
SSH: user pi, password natur. Drop a public-key file at /boot/firmware/authorized_keys on the card; it is installed for pi on boot. root accepts only the manufacturer key, and pi has no sudo.
Wi-Fi hotspot: SSID follows the hostname, PSK BirdsAndBats. The station is 169.254.0.1.
Web: Caddy on port 80, and optionally HTTPS on port 443 with a per-device certificate — tsconfig at / and FileBrowser Quantum at /data/ (WebDAV at /data/dav/data/). Both ask for a login with the pi password. See tsOS-base security.
Runtime settings live on the VFAT boot partition (/boot/firmware on the Pi). Edit on the card, then reboot.
| File | Purpose |
|---|---|
cmdline.txt |
systemd.hostname=, timezone=, first-boot repartition |
radiotracking.ini |
pyradiotracking (example) |
mosquitto.d/ |
Extra Mosquitto broker configs (include_dir) |
wireguard.conf |
WireGuard interface |
authorized_keys |
SSH keys for pi, read in place by sshd |
geolocation |
Configured station position, used by tslocation |
Platform files other than radiotracking.ini come from tsOS-base. See that project's boot configuration.
In tsconfig, saving and deploying configuration are separate actions — use Deploy after saving changes that should take effect on the station.
/data is the station data volume (ExFAT datafs after first-boot repartition, or a USB disk). radiotracking.service writes CSV detections there. FileBrowser Quantum roots at /data.
tsupdate applies OTA images using Raspberry Pi tryboot, with automatic rollback if the new image fails to boot. Operator overview: tsOS-base updatability. GitHub Releases may also attach pidiff update tarballs between consecutive images.
- RTL-SDR dongles (R802T): staged gains
lna_gain,mixer_gain,vga_gainvia the librtlsdr fork - Plus tsOS-base hardware: WittyPi 4, GPS, LTE, watchdog — tsOS-base hardware
Images are two-stage: a published tsOS-base zip (currently 2027.0.10), then this repo's Pifile via pimod v0.9.3 (docker-compose.yml):
docker-compose run --rm pimod pimod.sh tsOS-vhf.Pifile- Developer documentation — architecture, build, project structure
- Radiotracking — configuration, outputs, recovery, troubleshooting
- tsOS-base — overlayroot, partitions, OTA, shared services
- CHANGELOG.md
If you use tsOS-vhf in academia, please cite Höchst & Gottwald et al.
J. Höchst, J. Gottwald, P. Lampe, J. Zobel, T. Nauss, R. Steinmetz, and B. Freisleben, “trackIT OS: Open-source Software for Reliable VHF Wildlife Tracking,” in 51. Jahrestagung der Gesellschaft für Informatik, Digitale Kulturen, INFORMATIK 2021, Berlin, Germany, 2021.
@inproceedings{hoechst2021trackIT,
title = {{trackIT OS: Open-source Software for Reliable VHF Wildlife Tracking}},
author = {Höchst, Jonas and Gottwald, Jannis and Lampe, Patrick and Zobel, Julian and Nauss, Thomas and Steinmetz, Ralf and Freisleben, Bernd},
booktitle = {51. Jahrestagung der Gesellschaft f{\"{u}}r Informatik, Digitale Kulturen, {INFORMATIK} 2021, Berlin, Germany},
series = {{LNI}},
publisher = {{GI}},
month = sep,
year = {2021}
}