Skip to content

Commit

Permalink
updated readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jonashoechst
jonashoechst committed Sep 5, 2024
1 parent b3b1221 commit 166d296
Showing 1 changed file with 15 additions and 47 deletions.
62 changes: 15 additions & 47 deletions Readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,29 @@
# tRackIT OS
[![Build tRackIT OS](https://github.com/tRackIT-Systems/tRackIT-OS/actions/workflows/build_trackit_os.yml/badge.svg)](https://github.com/tRackIT-Systems/tRackIT-OS/actions/workflows/build_trackit_os.yml)
[![Build BatRack OS](https://github.com/tRackIT-Systems/tRackIT-OS/actions/workflows/build_batrack_os.yml/badge.svg)](https://github.com/tRackIT-Systems/tRackIT-OS/actions/workflows/build_batrack_os.yml)
# trackIT OS
[![Build trackIT-OS Images](https://github.com/tRackIT-Systems/tRackIT-OS/actions/workflows/build.yml/badge.svg)](https://github.com/tRackIT-Systems/tRackIT-OS/actions/workflows/build.yml)

tRackIT OS is an open-source software for reliable VHF radio tracking of (small) animals in their wildlife habitat. tRackIT OS is an operating system distribution for tRackIT stations that receive signals emitted by VHF tags mounted on animals and are built from low-cost commodity-off-the-shelf hardware. tRackIT OS provides software components for VHF signal processing, system monitoring, configuration management, and user access. In particular, it records, stores, analyzes, and transmits detected VHF signals and their descriptive features, e.g., to calculate bearings of signals emitted by VHF radio tags mounted on animals or to perform animal activity classification.
trackIT OS is an open-source software for reliable VHF radio tracking of (small) animals in their wildlife habitat. trackIT OS is an operating system distribution for trackIT stations that receive signals emitted by VHF tags mounted on animals and are built from low-cost commodity-off-the-shelf hardware. trackIT OS provides software components for VHF signal processing, system monitoring, configuration management, and user access. In particular, it records, stores, analyzes, and transmits detected VHF signals and their descriptive features, e.g., to calculate bearings of signals emitted by VHF radio tags mounted on animals or to perform animal activity classification.


## Download

The image of tRackIT OS can be downloaded in the [GitHub Releases](https://github.com/tRackIT-Systems/tRackIT-OS/releases) section of this repository.
## Build tRackIT OS
The image of trackIT OS can be downloaded in the [GitHub Releases](https://github.com/trackIT-Systems/trackIT-OS/releases) section of this repository.

The base tRackIT OS build consists of two stages. First, a `Base.img` is built, which installs all required software and might take some time to be build. Secondly the custom software components and configuration files are copied and installed and `tRackIT-OS.img` is built.
## Build trackIT OS

```sh
$ docker-compose run --rm pimod pimod.sh Base.Pifile
### FROM https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2023-05-03/2023-05-03-raspios-bullseye-arm64-lite.img.xz
Using cache: .cache/downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2023-05-03/2023-05-03-raspios-bullseye-arm64-lite.img.xz
### TO Base-arm64.img
Moving temporary /tmp/tmp.vvqN5fe4xU to Base-arm64.img
...
The base trackIT OS build consists of two stages. First, a base image is built, which installs all required software and might take some time to be build, see [https://github.com/tRackIT-Systems/tsOS-Base](tsOS-Base). Secondly the custom software components and configuration files are copied and installed and `trackIT-OS.img` is built.

```sh
$ docker-compose run --rm pimod pimod.sh tRackIT-OS.Pifile
### FROM Base-arm64.img
Copying Base-arm64.img to tRackIT-OS.img.
### FROM https://github.com/tRackIT-Systems/tsOS-Base/releases/download/2024.07.2/tsOS-Base-arm64-2024.07.2.zip
Fetching remote: https://github.com/tRackIT-Systems/tsOS-Base/releases/download/2024.07.2/tsOS-Base-arm64-2024.07.2.zip
...
```

### Targets

As of May 2023, two versions of tRackIT OS exist, build for armhf and arm64. The reasoning behind that is, that some camera software requires 32-bit libraries, which in turn are required by BatRack.

`Base.Pifile` and `tRackIT-OS.Pifile` are using arm64 as their primary target. However there exist `-armhf` versions which create their 32-bit counterparts. `BatRack-OS.Pifile` depends on `tRackIT-OS-armhf.img`, hence this image needs to be build first.
As of September 2024, two versions of tRackIT OS exist, build for `armhf` and `arm64`. The reasoning behind that is, that some camera software requires 32-bit libraries, which in turn are required by BatRack.

## Build BatRack OS

BatRack OS requires three stages of building, as it is based upon tRackIT OS. As the camera drivers only work in the 32-bit OS, the stages differ slightly:

```sh
$ docker-compose run --rm pimod pimod.sh Base-armhf.Pifile
### FROM https://downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2023-05-03/2023-05-03-raspios-bullseye-armhf-lite.img.xz
Using cache: .cache/downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2023-05-03/2023-05-03-raspios-bullseye-armhf-lite.img.xz
### TO Base-armhf.img
Moving temporary /tmp/tmp.7JMz4fdunp to Base-armhf.img
...

$ docker-compose run --rm pimod pimod.sh tRackIT-OS-armhf.Pifile
### FROM Base-armhf.img
### TO tRackIT-OS-armhf.img
Copying Base-armhf.img to tRackIT-OS-armhf.img.
...

$ docker-compose run --rm pimod pimod.sh -d BatRack-OS.Pifile
### FROM tRackIT-OS-armhf.img
### TO BatRack-OS.img
Copying tRackIT-OS-armhf.img to BatRack-OS.img.
...
```
`tRackIT-OS.Pifile` is using arm64 as their primary target. However there exist `-armhf` versions which create their 32-bit counterparts.

## Configuration

Expand All @@ -65,11 +33,11 @@ The system can be configured through different files in the `/boot` partition.

`cmdline.txt` holds the kernel boot commandline, which allows to configure the hostname in newer systemd versions. This behavioud is emulated and a hostname can be configured by setting `systemd.hostname=tRackIT-00001`

### [`/boot/firmware/radiotracking.ini`](boot/radiotracking.ini)
### [`/boot/firmware/radiotracking.ini`](boot/firmware/radiotracking.ini)

Hold the configuration of `pyradiotracking`, [see example config](https://github.com/tRackIT-Systems/pyradiotracking/blob/master/etc/radiotracking.ini).

### [`/boot/firmware/mqttutil.conf`](boot/mqttutil.conf)
### [`/boot/firmware/mqttutil.conf`](boot/firmware/mqttutil.conf)

Mqttutil reports system statistics via MQTT, [see example config](https://github.com/tRackIT-Systems/pymqttutil/blob/main/etc/mqttutil.conf).

Expand All @@ -78,13 +46,13 @@ Mqttutil reports system statistics via MQTT, [see example config](https://github

A wireguard configuration can be set using this configuration file.

### [`/boot/firmware/mosquitto.d/`](boot/mosquitto.d/)
### [`/boot/firmware/mosquitto.d/`](boot/firmware/mosquitto.d/)

Files in this directory are loaded by mosquitto. E.g. mqtt brokers for reporting can be set using files in this folder.

## Scientific Usage & Citation

If you are using tRackIT OS in academia, we'd appreciate if you cited our [scientific research paper](https://jonashoechst.de/assets/papers/hoechst2021tRackIT.pdf). Please cite as "Höchst & Gottwald et al."
If you are using trackIT OS in academia, we'd appreciate if you cited our [scientific research paper](https://jonashoechst.de/assets/papers/hoechst2021tRackIT.pdf). Please cite as "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.
Expand Down

0 comments on commit 166d296

Please sign in to comment.