Skip to content
trackIT-SystemsPublic

About

Open-source Software for Reliable VHF Wildlife Tracking

Resources

Stars

12 stars

Watchers

4 watching

Forks

 
 

Repository files navigation

tsOS-vhf

Build tsOS-vhf Images GitHub Release

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).

What's in the image

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 as pi in 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.

Download and flash

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.

First access

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.

Boot configuration

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.

Storage

/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.

Updates

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.

Hardware

  • RTL-SDR dongles (R802T): staged gains lna_gain, mixer_gain, vga_gain via the librtlsdr fork
  • Plus tsOS-base hardware: WittyPi 4, GPS, LTE, watchdog — tsOS-base hardware

Build

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

Further reading

Citation

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}
}

About

Open-source Software for Reliable VHF Wildlife Tracking

Resources

Stars

12 stars

Watchers

4 watching

Forks

Releases

Packages

Contributors

Languages