git.io/wow - signal visualizer
wow
(pronounced "") is
a tool for viewing and analyzing radio signals captured by SDR platforms such as
the HackRF via
hackrf_transfer
.
A secondary objective of the project is to serve as a learning tool. If you're into SDR, or you're curious about how to write a cross-platform GUI app, hopefully something in here might be useful to you.
MIT. Use the code however you want. Take it and build at least n - 1
companies with it.
Currently the software is in pre-alpha. In fact, it does nothing whatsoever except display a blank form. (Though if you happen to live in a faraday cage, this visualization might not be entirely inaccurate.)
Eventually you'll be able to analyze signal files by running wow some-signal-recording.iq
, where some-signal-recording.iq
is filled
with quadrature samples from hackrf_transfer
. Someday it might be
able to analyze most types of signal files including wav files, etc,
but the first goal is to produce something minimally useful for the
HackRF community.
wow
is cross-platform. It was designed from the ground up to run
pretty much anywhere that runs mono
or Windows. I'm very interested
in getting it working on BSD, but I have no experience with BSD# yet.
It'd be pretty sweet if anyone could help me figure out this part, but
unfortunately I have nothing to reward you with except some dry humor,
an honorary mention in an exclusive "Credits" section (so exclusive it
doesn't even exist yet), and my eternal gratitude (which sadly isn't
edible.)
I'd be very grateful if you'd try out wow
and verify it runs on
your platform, in spite of the fact that it doesn't do anything useful
yet. If there are any pain points during the install process, please
let me know. (See 'installation' section below.) Also let me know if
it's not completely painless to build it from source. (See 'build'
section below.)
I've often noticed that some software projects can be extremely tricky to build from source, depending on your platform, so I'm trying to make "it's a pleasure to build this from source!" a first-class feature from the very beginning of this project. Maybe it'll encourage people to tinker with the code or submit a pull request.
The current plan is to get a basic spectrogram visualizater up and
running as quickly as possible, choosing to release one tiny feature
at a time in rapid succession. I intend to follow GitHub
Flow; in particular,
the master
branch should always contain working code, and feature
additions should be small and frequent. Release whenever a feature
has been added and it hasn't broken anything.
Install the dependencies for your platform:
Pop open a beer, 'cause there ain't no thang for you to do but to head down to installation step 2. Scroll down like it's 1968!
Paste this into your terminal:
cat <<'EOF' > wow_such_debian.sh
# update your sources.
sudo apt-get update
# install git and checkout the repo.
sudo apt-get install git -y
# install realpath.
sudo apt-get install realpath -y
# install Mono. Time to go grab a cup of coffee Kappa
sudo apt-get install mono-complete -y
# install build dependencies.
sudo apt-get install build-essential libc6-dev-i386 -y
EOF
# install the dependencies.
bash ./wow_such_debian.sh;
Paste this into a Terminal window:
cat <<'EOF' > wow_such_osx.sh
# sudo privs will be required later for brew cask.
sudo echo
# install Homebrew. http://brew.sh
if [ -z "`which brew`" ]; then
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)";
fi
# update Homebrew.
brew update
# install `realpath`
if [ -z "`which realpath`" ]; then
brew tap strayptr/tap
brew install realpath
fi
# install `git`
if [ -z "`which git`" ]; then brew install git; fi
# install `mono`.
if [ -z "`which mono`" ]; then
# we also need libgdiplus, which doesn't come with `brew install
# mono`. See https://github.com/Homebrew/homebrew/pull/34973
# Let's install mono from `brew cask` instead.
# install cask, the brew binary package manager.
brew install caskroom/cask/brew-cask
# install the full mono-mdk from cask.
brew cask install mono-mdk
fi
EOF
# install the dependencies.
bash ./wow_such_osx.sh;
Go to the Releases page (https://git.io/wow-many-release) and download the latest archive, such as wow-v0.0.1.tar.gz.
- Extract the archive, which produces a folder structure like
wow-0.0.1/wow/...
(Note: If https://git.io/wow-many-release doesn't suit your tastes, a number of alternatives have been prepared):
- To launch the visualizer, navigate to
wow-0.0.1/wow/bin
and double click onwow
(orwow.cmd
on Windows).
(Or run wow-0.0.1/wow/bin/wow
in a terminal window or a cmd.exe
window. Same thing.)
The folder you got from the archive file is portable, i.e. bin/wow
will probably run properly no matter where you put it or how you
launch it. So feel free to put it wherever you want; just add the
subfolder wow/bin
to your PATH.
Eventually there will probably be some snazzy installer with snazzy installer features, but in the meantime here's some boilerplate recipes.
To install wow
:
Linux users: Copy wow-x.y.z/wow
to /usr/local/wow
then add the
bin folder to your PATH: export PATH="$PATH:/usr/local/wow/bin"
.
Now you can run wow
from anywhere. Thrilling.
Windows users: Create a shortcut to wow.cmd
on your desktop.
Name it something like help im trapped in a shortcut factory
. You
could also add C:\wow-0.0.1\wow\bin
to your PATH if you want to
launch wow from a cmd.exe terminal (assuming you extracted the release
archive to C:\
).
Install the dependencies via installation step 1 above. It includes everything you need to build from source.
Paste this into your terminal:
# get the code.
git clone https://github.com/strayptr/wow && cd wow
# build the project, then switch to the output folder it generated.
etc/make_build.py && cd build/wow-such-signal
If there were no build errors, you'll end up inside a folder path like
build/wow-such-signal
. The wow-such-signal
folder is analogous
to the folder you'd get from extracting a release archive, like
wow-v0.0.1/
. It's a self-contained directory structure which can
be copied anywhere else and has no external dependencies, i.e. it's
a portable installation.
Really, I'm making it sound more complicated than it is: just run
wow/bin/wow
in your terminal and the visualizer should launch.
Now you can goto installation step 3 above and pretend like it's the folder you got from a release archive.
--
The process of making an actual release is exactly the same, except you pass in a version number:
-
run
etc/make_build.py --version x.y.z
where x/y/z are major/minor/revision versions. This will produce abuild/wow-x.y.z.tar.gz
file. -
create a GitHub release and attach the
wow-x.y.z.tar.gz
file.
--
This README is probably way too long and wordy, but, with apologies, at this point I think I should stop trying to write READMEs / build methodologies and start writing useful signal analysis code.
--
Pull requests welcome! I'd be like
We use XMind to keep track of notes, ideas, design decisions, cornercase troubleshooting issues, etc.
Current mindmap: