ShinySDR Manual: Programmer's Guide

Architecture

Overview

ShinySDR runs as two independent processes. The server performs all DSP operations and communicates with the radio hardware. It is written in Python (2, not 3) and uses the frameworks GNU Radio for DSP and Twisted for networking. The client implements the user interface (including audio input/output); it lives entirely within a single web page and uses standard JavaScript, HTML, and web APIs. Communication between the client and the server is via HTTP and WebSocket.

Server

The server code has three principal functions:

TODO more here

Client

TODO client architecture, require.js, etc.

One of the design principles of the client is that reloading the page should lose no information. All state should be recorded on the server, in localStorage, or in the URL.

Plugins

ShinySDR plugins are defined based on the Twisted plugin system. A plugin is a Python module or package which exports objects implementing one of the defined plugin interfaces such as:

To be loaded, a plugin must be placed somewhere on your Python module search path (PYTHONPATH) in the shinysdr.plugins package. (In the future, there may be a method to add plugins from the configuration file.)

To add functionality, an instance of one of the plugin definitions must be declared at the top level of the module; for example, in basic_demod.py we can see code like

@implementer(IModulator)
class AMModulator(gr.hier_block2, ExportedState):
    ...

pluginDef_am = ModeDef(mode='AM',
    info=EnumRow(label='AM', sort_key=BASIC_MODE_SORT_PREFIX + 'AM'),
    demod_class=AMDemodulator,
    mod_class=AMModulator)

The important thing is that the module contains the ModeDef; the variable name does not matter.

[TODO: formally document plugin interfaces; embed/hyperlink here]

Design principles

TODO: Write more of this.

Testing

Automated testing and linting that should be done regularly:

  1. Run automated tests of Python code by running trial shinysdr. The trial utility is part of Twisted.

    (If you are using a MacPorts-packaged version of Twisted, note that it will have a Python-version suffix such as trial-2.7. I don't know whether any other package systems have a similar issue.)

  2. Lint code by running ./lint.sh

  3. Run automated tests of JavaScript code by visiting /test/.

Manual testing that can be done (when likely relevant):

Code style

General

Python

JavaScript

TODO