Contents


The repository is available on GitHub.

The available documentation is:

  • Everything on this website, built from the /docs folder on the repository.

  • Rustdoc documentation, generated from docstrings, built using cargo doc --document-private-items and available on /target/doc/noaa-apt/index.html

  • Also there are a lot of comments on the code because I tend to forget everything quite fast.

Code style

  • Should follow the Style guidelines but 80 characters as line width.

  • Docstrings: Try to document everything, follow RFC-1574 without using links or examples.

  • Order of use in code:

      extern crate thirdparty;
      pub mod ...;
      mod ...;
      pub use std::...;
      pub use thirdparty::...;
      pub use internal::...;
      use std::...;
      use thirdparty::...;
      use internal::...;
    

Website

I’m using Jekyll, the website is built automatically by GitHub from the /docs folder. These are the steps to build the website locally:

sudo apt-get install ruby-dev
gem install bundler jekyll
cd docs
jekyll build --baseurl "$(pwd)/_site/"

Notes:

  • I’m using a modification of Horizons-Jekyll-Theme.

  • Favicons generated using RealFaviconGenerator

  • Apparently, the theme used font-awesome to provide icons, I got rid of that.

  • Changed font to Open Sans and now I’m loading from default.html instead of style.css because it’s faster.

  • To set the sizes of youtube videos I use this.

Things to do

  • Important:

    • Add warnings for short images when reading telemetry.

    • Check things that can panic/can fail:

      • Integer substraction.

      • Slicing/indexing.

      • Functions that can panic.

      • Something else?.

      • Make sure that Rate cant overflow when resampling against strange sample rates.

  • Someday:

    • Show telemetry bands on GUI.

    • Log everything to a file, especially for Windows since it doesn’t have a console to see output.

    • Investigate about despeckle.

    • Make OSX binaries, I don’t have a Mac. I should cross-compile or get a virtual machine to work?.

    • Check OSX build dependencies, now on GNU/Linux we need libssl-dev.

    • Compile as a library and create an Android client

    • Implement false color algorithm by enigmastrat

    • Improve syncing performance. Make it faster and more resilent to noise, maybe working with the mean and variance?. Especially for Raspberry Pi.

    • Live decoding, from a TCP stream or using librtlsdr or from audio.

    • Add man page.

    • Show panics from the decoding thread on GUI. Looks like I have to wait until rust creates a simple way, the current alternatives are:

      • std::thread::JoinHandle::join() returns Err() on a panic, but blocks the GUI thread.

      • std::panic::catch_unwind works “only” for unwinding panics, maybe it’s enough?

      • #[panic_handler] looks useful for no_std applications.

Compilation

Build with --release, Rust does some optimizations and it works faster.

GNU/Linux

  • Install rustup (you need rustc --version at least 1.27.0).

  • sudo apt install libgtk-3-dev libssl-dev.

  • cargo build --release.

GNU/Linux portable

I can’t make gtk-rs to work with the x86_64-unknown-linux-musl target, so I’m building with the default x86_64-unknown-linux-gnu on Debian Stretch. I think the binary works on any linux with GLIBC newer than the one used when building, that’s why I’m using a Debian Jessie docker image.

So in the end, I build by releases with a Docker image: The GUI version, the no GUI version and the GUI .deb package. Also I build the Raspberry Pi versions (armhf).

  • Set up:

    • Install Docker.

    • Move to root folder on this repository.

    • docker build ./build/linux-gnu-docker/ -t noaa-apt-linux-build-image

    • docker create -v "$(pwd)":/home/rustacean/src --name noaa-apt-linux-build noaa-apt-linux-build-image

  • Building the binaries:

    • docker start -ai noaa-apt-linux-build
  • The binaries/packages are on ./target/docker_builds

Mac / OSX

  • Install rustup (you need rustc --version at least 1.27.0). The ‘unix installer’ is fine for Macs.

  • Install dependencies via Homebrew. I’m not entirely sure if these are enough: brew install gtk+3 adwaita-icon-theme openssl.

  • cargo build --release.

Windows portable

I never tried to compile from Windows, I cross-compile from GNU/Linux to Windows. I tried to get a mingw64-gtk environment to work on Debian without success. So I use a modification of a Docker image I found here.

  • Set up:

    • Install Docker.

    • Move to root folder on this repository.

    • docker build ./build/windows-gnu-docker/ -t noaa-apt-windows-build-image

    • docker create -v $(pwd):/home/rustacean/src --name noaa-apt-windows-build noaa-apt-windows-build-image.

  • Building the package:

    • docker start -ai noaa-apt-windows-build.
  • The binaries/packages are on ./target/docker_builds

Raspberry Pi

I’m building it using the same docker container I use for GNU/Linux portables.

Tests

Unit tests are located on the bottom of every module.

cargo test

Also, for GNU/Linux I have a bash script that runs the program on WAV files located on /test/. Results are on /test/results/, check with Audacity.

./test/test.sh

I use Clippy too:

  • cargo clippy -- -A clippy::ptr_arg: Should have no warnings.

  • cargo clippy -- -A clippy::ptr_arg -W clippy::pedantic: Check once in a while but ignore most of the lints

Release checklist

  • Update dependencies: cargo update.

  • Unit tests: cargo test.

  • Get previous tags from remote and check latest version, just in case:

      git fetch --tag
      git tag -l
    
  • Increment version number on /Cargo.toml.

  • Increment version number on /docs/version_check.

  • Increment version number on /src/program.rc.

  • Write changelog on /debian/changelog.

  • Edit the Downloads page on the website, point to the new packages that are going to be uploaded.

  • Build using Docker for:

    • GNU/Linux.

    • GNU/Linux without GUI.

    • Windows.

  • Check required glibc version, should be less than the version shown on the Download page. Use /build/check_glibc.sh, e.g.: ./build/check_glibc.sh ./target/docker_builds/noaa-apt-?.?.?-x86_64-linux-gnu/noaa-apt

  • Check archives, names should be:

    • noaa-apt-?.?.?-x86_64-linux-gnu.zip

    • noaa-apt-?.?.?-x86_64-linux-gnu-nogui.zip

    • noaa-apt-?.?.?-armv7-linux-gnueabihf.zip

    • noaa-apt-?.?.?-armv7-linux-gnueabihf-nogui.zip

    • noaa-apt_?.?.?-1_amd64.deb

    • noaa-apt-?.?.?-x86_64-windows-gnu.zip

  • Test both GNU/Linux builds using /test/test.sh.

  • Test Windows version.

  • Test Raspberry Pi version.

  • Optionally test .deb on Ubuntu VM.

  • Create tag on git, e.g.: git tag v0.9.2.

  • Push tag, e.g.: git push origin v0.9.2.

  • Edit release on GitHub. Leave “Release title” empty, leave changelog as description. Upload files.

Check for updates

The program sends a HTTP GET request and receives the latest version available, the URL is https://noaa-apt.mbernardi.com.ar/version_check?{current version}.

The currently installed version is sent just in case I want to track which versions are being used by people. Anyways, for now I delegated the noaa-apt to Github and version_check is just a static file being served using Github pages, so currently I’m not logging any information. In the future I won’t log anything other than the currently installed version.

If you want to disable this you can do it from the configuration file.

Misc

  • When I tried to UDP stream from GQRX to localhost it didn’t work, I had to change the address to 127.0.0.1.

  • Sizes for Windows icons: 16x16, 32x32, 48x48, and 256x256. Icons generated using the script /build/generate_windows_icon.sh.

  • Decode of argentina.wav on Raspberry Pi took approx 36s with WXtoImg (pristine, no map, no despeckle) and 46s with noaa-apt using the fast profile.

Thank you to

  • RTL-SDR.com: For writing a blog post.

  • pietern: I took the AM demodulator from his apt137 decoder.

  • Grant T. Olson: OSX build instructions.

  • FMighty: Helped with cross compilation to Raspberry Pi.

  • Peter Vogel: For writing about noaa-apt on the web.

  • wren84 and Florentin314: Reported problems with decoded images.

  • Gagootron, xxretartistxx and unknownantipatriot: Provided example images of missing samples.

References