Open Radar Code Architecture

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.

2 - Default Setup for the Raspberry Pi

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

Use this when setting up your Raspberry Pi on initial boot-up.

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.

Runtime 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:

Connect and Control Options

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

Most of the time, the Pi doesn’t need an internet connection. There are, however, a couple of cases where you may want some sort of a network connection to the Pi.

These are:

Downloading data from the Pi to a computer (requires a network connection but not internet)
Initial setup with cloud-init (requires internet)
Updating code by pulling from GitHub (requires internet)

There are three potential ways to communicate with the Raspberry Pi; direct control, ethernet, or via Wi-Fi. The Raspberry Pi as set up does not have a graphical user interface (GUI). After initial set-up, if the user wants to add remote access or move files onto the Pi, they wil need to do so using direct control. Direct control uses Secure Shell (ssh) protocol.

Network Configuration

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

Setting up network interfaces

With cloud-init (first-time setup)

The preferred way to setup network interfaces is by providing them in the network-config file read by cloud-init when first setting up the Pi.

An example is shown below:

# This file contains a netplan-compatible configuration which cloud-init will
# apply on first-boot (note: it will *not* update the config after the first
# boot). Please refer to the cloud-init documentation and the netplan reference
# for full details:
#
# https://cloudinit.readthedocs.io/en/latest/topics/network-config.html
# https://cloudinit.readthedocs.io/en/latest/topics/network-config-format-v2.html
# https://netplan.io/reference

version: 2
ethernets:
 eth0: # Your ethernet name.
 dhcp4: no
 addresses: [192.168.11.137/24]
 gateway4: 192.168.11.1
 nameservers:
 addresses: [8.8.8.8,8.8.4.4]
wifis:
 renderer: networkd
 wlan0:
 dhcp4: true
 optional: true
 access-points:
 "<YOUR WIFI SSID HERE>":
 password: "<YOUR WIFI PASSWORD HERE>"

The above configuration sets up a static IP over the ethernet interface. It also configures 192.168.11.1 as the default gateway. This allows for sharing an internet connection from a computer over this interface if desired.

6 - Testing Layout

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

Indoor Testing

While indoors, make sure not to transmit any signals with the antenna. Only transmit into the spectrum analyzer or in a loopback configuration to the SDR.

Before doing any testing in a loopback configuration, use the spectrum analyzer to confirm that the transmitted power is less than the maximum input power the SDR can handle.

When connecting any SMA cable, make sure to hold the cable and connection point still while you connect it so that the cable does not spin as you tighten the nut, as this can cause damage to the pin. Tighten the nut using the SMA torque wrench (the wrench will bend when the proper tightness is reached).

File Formats

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

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.

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

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

Use Code for ORCA

Find the code for ORCA at the GitHub website. ORCA is contained in a folder called uhd_radar. The supplied link give useful information on how to install ORCA, history of past updates, and how to run the code.

Search Results

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