ShinySDR Manual: Installation

1. Install major dependencies

The following software is required to run ShinySDR. All of it will typically be available in your choice of package manager.

Python 2.7 or later compatible version (not Python 3).
GNU Radio 3.7.4 or later.
gr-osmosdr, and any applicable hardware drivers such as librtlsdr. (Plugins may be written to use other RF sources, but the only built-in support is for gr-osmosdr.)

The following software is optional; if it is installed, ShinySDR will automatically enable the relevant features.

hamlib (for controlling external hardware radios in a “sound card” setup).
gr-air-modes (for receiving ADS-B, aircraft transponders).
gr-radioteletype (for receiving RTTY and PSK31).
WSJT-X (for receiving WSPR).
multimon-ng (for receiving APRS).
rtl_433 (for receiving miscellaneous telemetry).
gr-dsd (for receiving digital voice modes supported by DSD).

2. Download ShinySDR

Obtain a copy of the source tree for ShinySDR. The usual command for this is

git clone https://github.com/kpreid/shinysdr/

which will create a directory named shinysdr.

3. Decide which way you want to install ShinySDR

There are two different ways you can go about installing and running ShinySDR, and now you need to know which ones you are planning to use.

You may use the standard Python module/application install process, setup.py; this will copy it to an appropriate location on your system and add a command-line program shinysdr. This is the most convenient way if you are not planning to make changes to the source code.
You may run it directly from the source tree, skipping the install step; this is convenient for development because changes take effect immediately.

You can do both of these, if you like; the only hazard is being confused about which version you are running.

4a. `setup.py`-style installation

If you intend to run ShinySDR directly from the source tree only, skip this step.

ShinySDR provides a setup.py script in the usual fashion for Python packages.

# system-wide installation
python setup.py build
sudo python setup.py install

# current user only
python setup.py install --user

For more installation options see python setup.py install --help and general documentation about how to install Python libraries.

[TODO: change this to talk about pip, not using setup.py directly.]

4b. Preparation to run from source tree

If you do not intend to run ShinySDR directly from the source tree, skip this step. Otherwise:

Install the following Python libraries:
- Twisted 12.3.0 or later.
- six.
- txWS 0.8 or later.
- PyEphem 3.7.5.1 or later.
- pyserial (optional: required only by hamlib plugin).
Run python setup.py fetch_deps. This will download JavaScript and other non-Python dependencies of ShinySDR.
You may wish to create a script to make it easy to start ShinySDR using this directory; for example, I have one like so:
```
#!/bin/sh
export PYTHONPATH="/wherever/you/put/shinysdr/"
exec python -m shinysdr.main "$@"
```

5. Configure the server

The server needs a configuration directory where the configuration and state of the server is stored. To create one, run

shinysdr --create config-dir-name

where config-dir-name is the pathname for where you would like the configuration directory created (it can be anywhere). You can then edit config-dir-name/config.py to tell ShinySDR about your hardware, what port(s) you would like it to listen on, and so on; see the page Configuration for details. (The default configuration assumes you have one RF hardware device of a type supported by gr-osmosdr.)

6. Start the server

Run

shinysdr config-dir-name

where config-dir-name is the same as in the previous step. The server will show the URL to visit, or you can use the --go option which will attempt to open it in your default browser.

Note: ShinySDR does not need to run as root. Please don't. (If you get a permission error trying to access USB devices on Linux then you need to install the rtl-sdr udev rules or unplug-replug the device if that's already been done.)

Note: Installing ShinySDR does not do anything to start the server at system boot or restart it if crashed. You will have to provide that on your own if you wish.

See the page Operation for what to do now that you have the server running.