Sylphase SDGPS
The software-defined GPS(/GNSS) toolkit
README

sdgps - The software-defined GPS(/GNSS) toolkit

NOTE: This SDGPS release only supports operation during the following range of dates: 2019-04-07 - 2038-11-21 This is due to the choice made in resolving the 1024-week ambiguity of the GPS L1 NAV WN field.

PREREQUISITES

Supported operating systems:

  • Ubuntu 20.04 LTS (focal) amd64/arm64
  • Ubuntu 22.04 LTS (jammy) amd64/arm64

First, enable passwordless sudo by following the below procedure. Many scripts in SDGPS assume that passwordless sudo access is available.

  1. Run sudo visudo
  2. Find the following line: %sudo ALL=(ALL:ALL) ALL
  3. Change it to: %sudo ALL=NOPASSWD:ALL
  4. Save the file and exit (in nano, the default editor, that would be <Ctrl-O><Enter><Ctrl-X>)

Run the following to apt install all the dependencies that sdgps requires. If it fails, you may need to enable the "universe" package repository by running sudo add-apt-repository universe. 

sudo apt-get update && sudo doc/install_deps

Run the following after cloning or pulling to get submodule contents: 

git submodule sync && git submodule update --init

Run the following to use ccache to make repeat compilation faster: 

ccache -F 0 -M 10G # limit cache to 10 GB
touch ~/.bashrc ~/.bash_aliases
sed -i '/ccache/d' ~/.bashrc ~/.bash_aliases # delete old line, if present
echo 'export PATH=/usr/lib/ccache:$PATH CCACHE_DIR=~/.ccache${SCHROOT_CHROOT_NAME+_}${SCHROOT_CHROOT_NAME}' >> ~/.bash_aliases
. ~/.bash_aliases # make changes take effect in this terminal

BUILDING

make -j`nproc` -l`nproc`

SETTING UP

While in the sdgps root directory, run the following commands to get the sdgps alias defined and setup tab completion: 

touch ~/.bash_aliases
sed -i '/sdgps_tab_complete.bash/d' ~/.bashrc ~/.bash_aliases # delete old line, if present
echo "source `pwd`/scripts/sdgps_tab_complete.bash" >> ~/.bash_aliases
. ~/.bash_aliases # make changes take effect in this terminal

After running those commands, you have to reopen your terminal to make the changes or run . ~/.bash_aliases to make the changes apply to an existing terminal.

At this point, tab completion should work. Test it by typing "sdgps<SPACE>" and then pressing TAB a few times. You should see a list of potential nodes to begin a pipeline with. The following aliases are also created to allow for tab completion when running sdgps with sudo or gdb:

  • sudosdgps - sudo sdgps
  • gdbsdgps - gdb -ex r --args sdgps
  • sudogdbsdgps - sudo gdb -ex r --args sdgps

While in the sdgps root directory, run the following commands to make the sdgps group, give it privileges to run sdgps (connect to hardware, gain realtime status), and add yourself to the sdgps group: 

sudo addgroup sdgps || true
sudo cp data/security-limits.conf /etc/security/limits.d/sdgps.conf
sudo cp data/sysctl.conf /etc/sysctl.d/90-sdgps.conf
sudo sysctl --load /etc/sysctl.d/90-sdgps.conf
sudo cp data/udev.rules /etc/udev/rules.d/99-sdgps.rules
sudo udevadm control --reload-rules
sudo udevadm trigger
sudo adduser `whoami` sdgps

After running those commands, you will have to log out and log back in or run sudo su $(whoami) to simulate that effect on a single terminal.

UPDATING SDGPS

To update, just run the following commands: 

git pull
sudo doc/install_deps # install any new dependencies
make -j`nproc` -l`nproc`

Look at CHANGELOG.md to see what has changed.

RUNNING IN REALTIME

Change the --antenna-position option to the XYZ position (in meters) of the antenna phase center in the INS coordinate system. 

sdgps sylphase-usbgpsimu2 --antenna-position '[1,2,3]' ! tracker ! decoder ! kf2 --output-rate 100 ! plot-solution

RECORDING

Change the --antenna-position option to the XYZ position (in meters) of the antenna phase center in the INS coordinate system. 

sdgps sylphase-usbgpsimu2-raw --antenna-position '[1,2,3]' ! write-raw-file recording1.raw --allow-overwrite

PLAYING BACK AND SOLVING WITH KF2

sdgps read-raw-file recording1.raw ! sylphase-usbgpsimu2-offline --deterministic ! tracker ! decoder ! kf2 --output-rate 100 ! plot-solution

SIMULATION WITH SIMPLE-PVT-SOLVER

To simulate raw RF samples, track satellite signals in software, and run simple-pvt-solver to compute a solution, run the following: 

sdgps generate-simple-trajectory --rate inf ! simulate-raw repofile:configs/simple ! sw-correlator --deterministic --acq-effort 0.3 ! tracker ! decoder ! simple-pvt-solver ! plot-solution

SIMULATION WITH KF2

To simulate raw RF samples, track satellite signals in software, and run the Kalman filter to compute a solution, run the following: 

sdgps generate-simple-trajectory --rate inf --angular-velocity-enu [0,0,1] ! simulate-raw repofile:configs/simple ! sw-correlator ! tracker ! decoder ! kf2 --output-rate 100 ! plot-solution

kf2 needs some rotation to initialize its magnetic calibration; --angular-velocity-enu [0,0,1] is there to provide that.

To run the prior command, but with hardware-accelerated correlation, run the following: 

sdgps generate-simple-trajectory --rate inf --angular-velocity-enu [0,0,1] ! simulate-raw ugi2: ! sylphase-usbgpsimu2-offline --deterministic ! tracker ! decoder ! kf2 --output-rate 100 ! plot-solution

To simulate at the correlation level, run the following, which will run faster than real-time: 

sdgps generate-simple-trajectory --rate inf --angular-velocity-enu [0,0,1] ! simulate-cooked repofile:configs/simple ! tracker ! decoder ! kf2 --output-rate 100 ! plot-solution

To simulate observables, run the following, which will run faster than real-time: 

sdgps generate-simple-trajectory --rate inf --angular-velocity-enu [0,0,1] ! simulate-observables repofile:configs/simple ! kf2 --output-rate 100 ! plot-solution

RUNNING UNIT TESTS

make test
make completetest # takes a while