Open Radar Code Architecture

Connecting to the Raspberry Pi

Mon, 01 Jan 0001 00:00:00 +0000

By default, the cloud-init script sets up a static IP of 192.168.11.137, but you could choose to configure this to something different for each payload box.

Our usual way of connecting is by plugging an ethernet cable into the Pi and connecting it to a laptop. You can read about all the networking options here.

SSH agent forwarding

If you need to authenticate to GitHub to download code, the recommended way is using SSH agent forwarding.

File Formats

Mon, 01 Jan 0001 00:00:00 +0000

Compatible hardware

Mon, 01 Jan 0001 00:00:00 +0000

Selecting a Software-Defined Radio (SDR)

ORCA is built upon the USRP Hardware Driver (UHD). As such, it is theoretically compatible with any Ettus SDR. We have primarily tested with B and X series devices (B205mini and X310, in particular), however most other Ettus SDRs should work with minor tweaks.

The basic capabilities of the two models we regularly use are detailed below:

SDR	Frequency Range (GHz)	Bandwidth (MHz)	Channels	Mass (kg)	Approximate Cost (USD)
X310 with UBX160	0.01-6	200	2 TX, 2 RX	1.7	$14,0000
B205mini-i	0.07-6	56	1 TX, 1 RX	0.024	$1,600

In general, we recommend B series devices for applications with constraints on size, weight, power, or budget. When capabilities beyond the B series are needed, we recommend the X series.

Sourcing Custom Parts

Mon, 01 Jan 0001 00:00:00 +0000

Many of the parts used to build Peregrine are custom designs. In some instances, these may be things you can build yourself if you have the right tools (3D printer, laser cutter, etc). In almost all cases, however, it is also possible to use our provided design files to order parts from reliable vendors. For each type of manufacturing, this page includes some notes about how we produce parts or which external vendors we have worked with.

Code overview

Mon, 01 Jan 0001 00:00:00 +0000

Conda environment setup

All of the required dependencies can be installed as a conda environment using the environment.yaml file in the repository. More instructions can be found in the README file.

Startup scripts

The X series devices require some initial network configuration. For convenience, a startup script is provided to automate this setup. You may need to tweak this file to your setup.

Runner scripts

The basic steps required to run the radar are:

Processing Functions

Mon, 01 Jan 0001 00:00:00 +0000

Configuration options

Mon, 01 Jan 0001 00:00:00 +0000

The entire configuration that controls the radar is defined in a single configuration file. This file is provided at runtime to run.py and encapsulates all of the settings needed to run various experiments on different hardware setups. Configuration files are specified in the YAML format and contained in the config/ folder of the ORCA repository. Default configuration files are included to run the code on a B205mini-i (default_b205.yaml1) and on an X310 (default_x310.yaml). Here we explain the basics behind the settings available to the user via the config file.

Postprocessing Notebooks

Mon, 01 Jan 0001 00:00:00 +0000

Debugging: Real-Time Clocks (RTC)

Mon, 01 Jan 0001 00:00:00 +0000

A real-time clock (RTC) is a small device equipped with a crystal oscillator and a battery that is responsible for keeping track of the current time, even while your computer (or Raspberry Pi) is powered off.

The “Payload Enclosure Divider” includes a PCF8523 RTC and a holder for a CR1220 coin cell battery. The provided user-config file should automatically set this up. As long as you provide internet access to the Pi once, it will automatically synchronize the RTC with a network time server and everything will just work.

Timing and timestamping

Mon, 01 Jan 0001 00:00:00 +0000

Timestamping of received data is relatively basic and not yet suitable for high-precision applications. This page describes the basics as currently implemented.

There is significant room to improve on ORCA here. USRP devices are capable of multiple means of synchronization between devices that could be used to provide better timestamping.

Relative timing of samples

Transmit and receive events are scheduled as timed commands. Generally, bursts of samples are recorded at intervals specified by pulse_rep_int.

Host computer transport parameter tuning

Mon, 01 Jan 0001 00:00:00 +0000

The maximum duty cycle you can achieve is a function of the SDR you use, the host computer, and the bandwidth you need. This page outlines suggestions for how to figure out an achievable duty cycle and what parameters can be tweaked to maximize this.

General process for benchmarking duty cycle

Determine the maximum achievable bandwidth with benchmark_rate

Use the USRP example benchmark_rate program (located at <path to conda install>/envs/<uhd environment name>/lib/uhd/examples) to determine the approximate maximum duty cycle you can achieve. For instance, with a Pi 4 and b205mini, I can reach about a 25% duty cycle – defined as sample rate divided by desired sample rate (14 Msps / 56 Msps in this case) – while consistently getting 0 dropped packets.

Data Storage Options

Mon, 01 Jan 0001 00:00:00 +0000

There are three tested options for how to store your radar data, with various tradeoffs:

MicroSD card – This is the default option that is assumed in the documentation.
External USB SSD or Flash Drive
NVMe SSD connected over PCIe interface (Pi 5 only)

MicroSD card

This is the easiest option since it’s built-in to the Raspberry Pi and requires no additional space or equipment.

MicroSD card quality varies significantly and counterfits are an issue. For this reason, purchasing from a reputable vendor is highly recommended.

Mon, 01 Jan 0001 00:00:00 +0000

T. O. Teisberg, A. L. Broome and D. M. Schroeder, “Open Radar Code Architecture (ORCA): A Platform for Software-Defined Coherent Chirped Radar Systems,” in IEEE Transactions on Geoscience and Remote Sensing, vol. 62, pp. 1-11, 2024, Art no. 5109411, doi: 10.1109/TGRS.2024.3446368.

Contributors, Citations, Contact Info, and Acknowledgements

Mon, 01 Jan 0001 00:00:00 +0000

Contributors, Citations, Contact Info, and Acknowledgements

Cite ORCA in your work

If you use ORCA, we would appreciate you citing our work. The currently preferred citation for all uses of ORCA is:

T. O. Teisberg, A. L. Broome and D. M. Schroeder, “Open Radar Code Architecture (ORCA): A Platform for Software-Defined Coherent Chirped Radar Systems,” in IEEE Transactions on Geoscience and Remote Sensing, vol. 62, pp. 1-11, 2024, Art no. 5109411, doi: 10.1109/TGRS.2024.3446368.

Customizing user-data

Mon, 01 Jan 0001 00:00:00 +0000

The default user-data we start from is as shown below. You will likely need to tweak many of these settings. Descriptions and tips for the most important sections are below.

Note that this is one of two key configuration files. You can read about network-config here.

Starting point user-data file

#cloud-config

# This is the user-data configuration file for cloud-init.
# The cloud-init documentation has more details:
#
# https://cloudinit.readthedocs.io/

system_info:
 default_user:
 name: ubuntu # Allow the default user to shutdown or reboot the system without entering a password (used by our automated scripts)
 sudo: "ALL=(ALL) NOPASSWD: /sbin/poweroff, /sbin/reboot, /sbin/shutdown"

# On first boot, set the (default) ubuntu user's password to "cryosphere"
chpasswd:
 expire: false
 users:
 - name: ubuntu
 password: $6$rounds=4096$aQ7tu0.beL3WAL32$fKxKYvZpY7EMCoxAU1heRomA3v8WvgbqBhhz08QwOtQdlP/DJOP2BThqZFoRW8d2a9PaIKK9BC9NHs1qNnkya1
 type: hash

# Enable password authentication with the SSH daemon
ssh_pwauth: true

# Set a default timezone
timezone: Etc/UTC

## Update apt database and upgrade packages on first boot
package_update: true
package_upgrade: true

## Install additional packages on first boot
packages:
- net-tools
- git
- cmake
- g++
- mosh
- exfat-fuse
- i2c-tools
- rpi.gpio-common
- util-linux-extra

## Write arbitrary files to the file-system
write_files:
- path: /home/ubuntu/initial_setup.sh
 content: |
 #!/bin/bash
 exec > >(tee -a "initial_setup_output.log") 2>&1
 # Miniconda Setup
 wget --progress=bar:force:noscroll "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh" -O $HOME/miniconda.sh
 bash $HOME/miniconda.sh -b -p $HOME/miniconda
 cd $HOME
 source .profile
 source miniconda/etc/profile.d/conda.sh
 conda init bash
 # Setup logger environment
 git clone git@github.com:thomasteisberg/uav_radar_logger.git
 # Clone uhd_radar repo
 git clone git@github.com:radioglaciology/uhd_radar.git
 cd uhd_radar
 #git checkout thomas/dask # Uncomment if you want to check out a specific branch other than main
 conda env create -n uhd -f environment-rpi.yaml
 conda activate uhd
 python /home/ubuntu/miniconda/envs/uhd/lib/uhd/utils/uhd_images_downloader.py
 systemctl --user enable radar.service
 systemctl --user enable logger.service
 ifconfig
 sudo reboot
 append: true
- path: /home/ubuntu/.profile
 content: |
 PATH=/home/ubuntu/miniconda/bin:$PATH
 source /home/ubuntu/.bashrc
 append: true
- path: /home/ubuntu/.ssh/known_hosts
 content: |
 github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
 github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
 github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
- path: /etc/security/limits.conf # Recommended by Ettus https://kb.ettus.com/USRP_Host_Performance_Tuning_Tips_and_Tricks
 content: |
 ubuntu - rtprio 99
 append: true
- path: /etc/systemd/user/radar.service
 content: |
 [Unit]
 Description=Service to run the radar code on startup

 [Service]
 Type=simple
 WorkingDirectory=/home/ubuntu/uhd_radar/
 ExecStart=/home/ubuntu/uhd_radar/manager/radar_service.sh

 Restart=always
 RestartSec=10

 KillSignal=SIGINT

 [Install]
 WantedBy=default.target
- path: /etc/systemd/user/logger.service
 content: |
 [Unit]
 Description=Service to log data from I2C sensors and automatically shutdown below a voltage threshold

 [Service]
 Type=simple
 WorkingDirectory=/home/ubuntu/uav_radar_logger/
 ExecStart=/home/ubuntu/uav_radar_logger/logger_service.sh

 Restart=always
 RestartSec=60

 KillSignal=SIGINT

 [Install]
 WantedBy=default.target

# Run arbitrary commands at rc.local like time
# These commands are run with root permissions
# If you want commands run as a normal user, put them in initial_setup.sh (see above)
# which is run as the "ubuntu" user (see below)
runcmd:
- chown -R ubuntu:ubuntu /home/ubuntu
- chmod +x /home/ubuntu/initial_setup.sh
- wget -O /etc/udev/rules.d/uhd-usrp.rules https://raw.githubusercontent.com/EttusResearch/uhd/master/host/utils/uhd-usrp.rules
- usermod -a -G i2c ubuntu
- usermod -a -G dialout ubuntu
- usermod -a -G tty ubuntu
- apt remove -y modemmanager
- systemctl stop serial-getty@ttyS0.service && systemctl disable serial-getty@ttyS0.service
- i2cdetect -y 1
- echo "dtoverlay=i2c-rtc,pcf8523" >> /boot/firmware/config.txt
- loginctl enable-linger ubuntu
- mkdir /media/ssd
- chown ubuntu /media/ssd
- chgrp ubuntu /media/ssd
- echo "/dev/sda2 /media/ssd exfat defaults,nofail,uid=1000,gid=1000 0 2" | tee -a /etc/fstab

Password-less shutdown

system_info:
 default_user:
 name: ubuntu # Allow the default user to shutdown or reboot the system without entering a password (used by our automated scripts)
 sudo: "ALL=(ALL) NOPASSWD: /sbin/poweroff, /sbin/reboot, /sbin/shutdown"

One of the features supported by the uav_radar_logger utility is to automatically cleanly shutdown the system if the measured battery voltage drops below a threshold. To facilitate this, the default user must be able to shutdown the system without needing additional authentication. This gives permission for the ubuntu user to call sudo shutdown or sudo reboot without entering a password.

Search Results

Mon, 01 Jan 0001 00:00:00 +0000