Skip to content

Fixed dead links, updated to match main repo #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 113 additions & 41 deletions docs/CONFIGURE.md

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions docs/DEBUG.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ make
gdb trunk-recorder core
```

6. *gdb* is a powerful debugging platform. However, all we need is a trace of the crash. After *gdb* has finished loading, type in `bt full` to get a trace. Copy all of the output from *gdb* into a new [GitHub Issue](https://github.com/robotastic/trunk-recorder/issues/new), along with as much information as possible on what maybe casuing the crash.
6. *gdb* is a powerful debugging platform. However, all we need is a trace of the crash. After *gdb* has finished loading, type in `bt full` to get a trace. Copy all of the output from *gdb* into a new [GitHub Issue](https://github.com/TrunkRecorder/trunk-recorder/issues/new), along with as much information as possible on what maybe casuing the crash.


# How to Capture an IQ Sample
Expand Down Expand Up @@ -67,7 +67,7 @@ Use the settings from the source you are interested in from your config.json fil

you would use: `rtl_sdr -f 855700000 -s 2048000 -g 39 -d 41 debug.iq`

The file that rtl_sdr generates is in a compact format... which is great but it can't easily be opened by other program. There is a good write-up on it from here (from 2014!). Luckily, some wrote a small program to convert it into a more standard format (complex IQ). I have included it in the /utils folder: [rtlsdr-to-iq.c](https://github.com/robotastic/trunk-recorder/blob/master/utils/rtlsdr-to-iq.c). Compile the program and then copy it to the directory with your recordings and run it against them. Note - the conversion will cause the filesize to increase 4x, so make sure you have enough space.
The file that rtl_sdr generates is in a compact format... which is great but it can't easily be opened by other program. There is a good write-up on it from here (from 2014!). Luckily, some wrote a small program to convert it into a more standard format (complex IQ). I have included it in the /utils folder: [rtlsdr-to-iq.c](https://github.com/TrunkRecorder/trunk-recorder/blob/master/utils/rtlsdr-to-iq.c). Compile the program and then copy it to the directory with your recordings and run it against them. Note - the conversion will cause the filesize to increase 4x, so make sure you have enough space.


## Playback in GQRX
Expand All @@ -81,4 +81,4 @@ You are then going to need a device string with the correct options. Update this

## Playing an IQ File as a Source in Trunk Recorder

Check out the [config-iq-file.json](https://github.com/robotastic/trunk-recorder/blob/master/examples/config-iq-file.json) config as an example of how to playback an IQ file as a Source. You will probably need to have the `repeat` parameter turned on, unless you have a really long file.
Check out the [config-iq-file.json](https://github.com/TrunkRecorder/trunk-recorder/blob/master/examples/config-iq-file.json) config as an example of how to playback an IQ file as a Source. You will probably need to have the `repeat` parameter turned on, unless you have a really long file.
2 changes: 1 addition & 1 deletion docs/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,5 +46,5 @@ Once **gdb** loads up, use the *backtrace* command to review the execution histo

`backtrace`

Now you can create a [GitHub Issue](https://github.com/robotastic/trunk-recorder/issues), including the info from **gdb**, along with your config.json and as much info as possible on how to recreate the crash.
Now you can create a [GitHub Issue](https://github.com/TrunkRecorder/trunk-recorder/issues), including the info from **gdb**, along with your config.json and as much info as possible on how to recreate the crash.

11 changes: 4 additions & 7 deletions docs/Install/INSTALL-DOCKER.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,12 @@ sidebar_position: 2
# Docker
If you are not going to be modifying the source code, **a [Docker](https://www.docker.com/) based install is the easiest way to get started.** Images are published frequently to [Docker Hub](https://hub.docker.com/r/robotastic/trunk-recorder). The images have GNURadio 3.8 and all other required dependencies built into it, so it should be ready to go and be a much faster solution than compiling. Images have been built for amd64 (amd64 is used by all modern Intel and AMD CPUs) and most popular flavors of ARM.

To get started, create a directory and place your **config.json** file there and a **talkgroup.csv** file if you are using one. Refer to [Configuring Trunk Recorder](CONFIGURE.md) for instructions on how to create these files.
To get started, create a directory and place your **config.json** file there and a **talkgroup.csv** file if you are using one. Refer to [Configuring Trunk Recorder](../CONFIGURE.md) for instructions on how to create these files.

```bash
docker run -it \
--privileged -e TZ=$(cat /etc/timezone) --user "$(id -u):$(id -g)" \
--device "/dev/bus/usb:/dev/bus/usb:rwm" -e TZ=$(cat /etc/timezone) --user "$(id -u):$(id -g)" \
-v $(pwd):/app \
-v /dev/bus/usb:/dev/bus/usb \
-v /var/run/dbus:/var/run/dbus \
-v /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket \
robotastic/trunk-recorder:latest
Expand All @@ -21,15 +20,14 @@ docker run -it \
To use it as part of a [Docker Compose](https://docs.docker.com/compose/) file:

```yaml
version: '3'
services:
recorder:
image: robotastic/trunk-recorder:latest
container_name: trunk-recorder
restart: always
privileged: true
devices:
- "/dev/bus/usb:/dev/bus/usb:rwm"
volumes:
- /dev/bus/usb:/dev/bus/usb
- /var/run/dbus:/var/run/dbus
- /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket
- ./:/app
Expand All @@ -56,4 +54,3 @@ Currently, Docker image builds are triggered by the following events:
* After every push to the `master` branch the `edge` tag is built and pushed to Docker Hub.
* Every day at 10 AM UTC the `nightly` tag is built and pushed to Docker Hub.
* When a new [release](https://github.com/robotastic/trunk-recorder/releases) happens the `<version>` and `latest` tags are built and pushed to Docker Hub.

4 changes: 2 additions & 2 deletions docs/Install/INSTALL-LINUX.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@ Now restart to make sure these drivers are not loaded.

## Configuring Trunk Recorder

The next step is to [configure Trunk Recorder](CONFIGURE.md) for the system you are trying to capture.
The next step is to [configure Trunk Recorder](../CONFIGURE.md) for the system you are trying to capture.

## Running trunk recorder.

Expand All @@ -224,4 +224,4 @@ From your build directory (e.g. `trunk-build`) you can now run

### Runtime options

Trunk Recorder will look for a *config.json* file in the same directory as it is being run in. You can point it to a different config file by using the *--config* argument on the command line, for example: `./trunk-recorder --config=examples/config-wmata-rtl.json`.
Trunk Recorder will look for a *config.json* file in the same directory as it is being run in. You can point it to a different config file by using the *--config* argument on the command line, for example: `./trunk-recorder --config=examples/config-wmata-rtl.json`.
41 changes: 26 additions & 15 deletions docs/Install/INSTALL-MAC.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,39 @@ sidebar_position: 4
There are two main "package managers" used on MacOS: [Homebrew](#using-homebrew) and [MacPorts](#using-macports). Trunk-recorder can be installed with dependencies from one or the other

## Using Homebrew
Tested on macOS Ventura 13.2 with the following packages:
Tested on macOS Sequoia 15.5 with the following packages:

- homebrew 3.6.21
- cmake 3.25.2
- gnuradio 3.10.5.1
- uhd 4.4.0.0
- pkgconfig 0.29.2
- homebrew 4.5.3
- cmake 4.0.2
- gnuradio 3.10.12.0_1
- uhd 4.8.0.0_1
- pkgconfig 2.4.3
- cppunit 1.15.1
- openssl 3.0.7
- fdk-aac-encoder 1.0.3
- sox 14.4.2
- pybind11 2.10.3
- openssl 3.5.0
- fdk-aac-encoder 2.0.3
- sox 14.4.2_6
- pybind11 2.13.6_1
- six 1.17.0

#### Install Homebrew
See [the Brew homepage](https://brew.sh) for more information.
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```

#### Installing using the Trunk Recorder Tap

Trunk Recorder can be installed easily by adding the repository to homebrew. More information can be found on [this github repo](https://github.com/TrunkRecorder/homebrew-install). Install can be done easily with the following commands.
```
brew tap trunkrecorder/install
brew install trunk-recorder
```

If you prefer to install packages individually or without adding the repository, it can be done using the instructions below.

#### Install GNURadio and other dependencies
```bash
brew install gnuradio uhd cmake pkgconfig cppunit openssl fdk-aac-encoder sox pybind11
brew install gnuradio uhd cmake pkgconfig cppunit openssl fdk-aac-encoder sox pybind11 six
```
#### Install the OsmoSDR Package for GNURadio
See the gr-osmosdr [homepage](https://osmocom.org/projects/gr-osmosdr/wiki/GrOsmoSDR) for more information.
Expand Down Expand Up @@ -71,7 +82,7 @@ sudo port selfupdate

#### Install GNU Radio

The preferred method for [installing GNU Radio](http://gnuradio.org/redmine/projects/gnuradio/wiki/InstallingGR) on macOS is:
The preferred method for [installing GNU Radio](https://wiki.gnuradio.org/index.php?title=MacInstall) on macOS is:

```bash
sudo port install gnuradio uhd gr-osmosdr
Expand Down Expand Up @@ -111,7 +122,7 @@ sudo make install
#### Building Trunk Recorder
```bash
mkdir trunk-recorder && cd trunk-recorder
git clone https://github.com/robotastic/trunk-recorder.git source
git clone https://github.com/TrunkRecorder/trunk-recorder.git source
mkdir build && cd build
cmake ../source -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl
make -j
Expand All @@ -120,11 +131,11 @@ sudo make install

## Configuring Trunk Recorder

The next step is to [configure Trunk Recorder](CONFIGURE.md) for the system you are trying to capture.
The next step is to [configure Trunk Recorder](../CONFIGURE.md) for the system you are trying to capture.

## Running trunk recorder.

If all goes well you should now have the executable named `trunk-recorder`, and created the `config.json` configuration file as described in the [Wiki](https://github.com/robotastic/trunk-recorder/wiki/Configuring-a-System) and [README](https://github.com/robotastic/trunk-recorder/blob/master/README.md#configure).
If all goes well you should now have the executable named `trunk-recorder`, and created the `config.json` configuration file as described in the [Wiki](https://github.com/TrunkRecorder/trunk-recorder/wiki/Configuring-a-System) and [Configuring Trunk Recorder](https://github.com/TrunkRecorder/trunk-recorder/blob/master/docs/CONFIGURE.md).

From your build directory (e.g. `trunk-build`) you can now run
`./trunk-recorder`
Expand Down
72 changes: 63 additions & 9 deletions docs/Install/INSTALL-PI.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Smaller radio systems can be covered using a Raspberry Pi. If you are interested
## RaspberryOS (aka Raspbian)

### Setup Raspbian
This is a [good guide](https://desertbot.io/blog/headless-raspberry-pi-4-ssh-wifi-setup) on how to setup a Raspberry Pi in headless mode. This means that you do not have to attach a monitor, keyboard or mouse to it to get it working. The steps below are pulled from this guide.
This is a [good guide](https://www.tomshardware.com/reviews/raspberry-pi-headless-setup-how-to,6028.html) on how to setup a Raspberry Pi in headless mode. This means that you do not have to attach a monitor, keyboard or mouse to it to get it working. The steps below are pulled from this guide.

#### Download and burn the image

Expand All @@ -21,7 +21,7 @@ The first step is to put the Raspberry Pi OS onto a MicroSD card. You will need

#### Setup for headless boot

After the OS has been written to MicroSD card, we need to change a few files so that the Pi can get on Wifi and also allow for SSH connections. See the [guide](https://desertbot.io/blog/headless-raspberry-pi-4-ssh-wifi-setup) for how to do it using Windows.
After the OS has been written to MicroSD card, we need to change a few files so that the Pi can get on Wifi and also allow for SSH connections. See the [guide](https://www.tomshardware.com/reviews/raspberry-pi-headless-setup-how-to,6028.html) for how to do it using Windows.

- **On a Mac** `touch /Volumes/boot/ssh`
- Next, add the WiFi info
Expand Down Expand Up @@ -66,13 +66,13 @@ deb https://www.deb-multimedia.org bookworm main non-free
```
- Download the keys for the apt source and install them:
```bash
wget https://www.deb-multimedia.org/pool/main/d/deb-multimedia-keyring/deb-multimedia-keyring_2016.8.1_all.deb
sudo dpkg -i deb-multimedia-keyring_2016.8.1_all.deb
wget https://www.deb-multimedia.org/pool/main/d/deb-multimedia-keyring/deb-multimedia-keyring_2024.9.1_all.deb
sudo dpkg -i deb-multimedia-keyring_2024.9.1_all.deb
```
- You can verify the package integrity with:
```bash
sha256sum deb-multimedia-keyring_2016.8.1_all.deb
9faa6f6cba80aeb69c9bac139b74a3d61596d4486e2458c2c65efe9e21ff3c7d deb-multimedia-keyring_2016.8.1_all.deb
sha256sum deb-multimedia-keyring_2024.9.1_all.deb
9faa6f6cba80aeb69c9bac139b74a3d61596d4486e2458c2c65efe9e21ff3c7d deb-multimedia-keyring_2024.9.1_all.deb
```
- Update the OS:
```
Expand All @@ -84,7 +84,13 @@ sudo apt upgrade
sudo apt -y install libssl-dev openssl curl git fdkaac sox libcurl3-gnutls libcurl4 libcurl4-openssl-dev gnuradio gnuradio-dev gr-osmosdr libhackrf-dev libuhd-dev cmake make build-essential libboost-all-dev libusb-1.0-0-dev libsndfile1-dev
```

Configure RTL-SDRs to load correctly:
- Remove xtra-dkms.
DKMS is not needed on the Raspberry Pi platform, and just causes issues. The above command actually returns an error on Raspberry Pi OS. So we remove that module from our build so we do not get errors from subsaquent `apt` calls.
```bash
sudo apt remove xtrx-dkms
```

## Configure RTL-SDRs to load correctly:

```bash
sudo wget https://raw.githubusercontent.com/osmocom/rtl-sdr/master/rtl-sdr.rules ~/rtl-sdr.rules
Expand All @@ -97,7 +103,55 @@ You will need to restart for the rules to take effect. Logging out and logging b
sudo shutdown -r now
```

Now go [Build](#build-trunk-recorder) Trunk Recorder!
## Configuring the UHD for Ettus SDRs

If you haven't setup UHD yet there are a few extra steps you need to take:

Install the UHD drivers:

```bash
sudo apt-get install libuhd-dev uhd-host
```

Download the firmware images. The location of the downloader is different than the error message:

```bash
dpkg -L uhd-host | grep "downloader"
```
The run the downloader at the location identified, it should be something like this:

```bash
sudo python3 /usr/libexec/uhd/utils/uhd_images_downloader.py
```

Setup the udev rules so any user can access the USB, as documented [here](https://files.ettus.com/manual/page_transport.html#transport_usb_udev):

```bash
cd /usr/libexec/uhd/utils/
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
```

## Building Trunk Recorder

In order to keep your copy of the Trunk Recorder source code free of build artifacts created by the build process, it is suggested to create a separate "out-of-tree" build directory. We will use `trunk-build` as our build directory. We by default do this in our home directory (`~` - Is a shortcut back to home.).

**Note:** Depending on the ammount of RAM in your Raspberry Pi, it may be best to run `make -j1` (2GB), `make -j3` (4GB), and `make -j4` (8GB) in order to ensure that you do not run out of RAM, at the cost of making the compile process take longer. If you ran out of RAM the compile process will fail competely, so it can be an acceptable tradeoff.

```bash
cd ~
mkdir trunk-build
git clone https://github.com/robotastic/trunk-recorder.git
cd trunk-build
cmake ../trunk-recorder
make -j1
sudo make install
```

## Configuring Trunk Recorder

The next step is to [configure Trunk Recorder](../CONFIGURE.md) for the system you are trying to capture.

***
# Ubuntu 22.04 Server (64-bit support!)
Expand Down Expand Up @@ -163,4 +217,4 @@ From your build directory (e.g. `trunk-build`) you can now run

### Runtime options

Trunk Recorder will look for a *config.json* file in the same directory as it is being run in. You can point it to a different config file by using the *--config* argument on the command line, for example: `./trunk-recorder --config=examples/config-wmata-rtl.json`.
Trunk Recorder will look for a *config.json* file in the same directory as it is being run in. You can point it to a different config file by using the *--config* argument on the command line, for example: `./trunk-recorder --config=examples/config-wmata-rtl.json`.
Loading