Difference between revisions of "BorIP Server"

Revision as of 23:16, 5 June 2012

Introduction

Please watch this demonstration video first. If you wish to see the demo on OS X, you can watch this one too.

Please see the BorIP to learn about the protocol.

More meat will be added to this page in due course!

Windows

The Windows server (available on the USRP Interfaces page) is a self-contained server with support for the same devices at the ExtIO plugin: Legacy/UHD USRP, Realtek RTL2832U-based DVB-T dongles, and the FUNcube Dongle.

Linux & Mac

This is available in the apps directory of gr-baz as a Python 2.x program:

./borip_server

NOTE: You must first check out the gr-baz code, compile and install it - this will make necessary dependencies available. There are more instructions regarding how to do this on the gr-baz page.

Currently, there is support for RTL2832U devices, and USRPs accessible with the Legacy host interface (not UHD, as yet).

Setting up OS X

Alain De Carolis says in this thread:

I am successfully running my Hama Nano on GNU Radio 3.3.0 installed via MacPorts with rtl-sdr and gr-baz on OSX 10.7 Lion.
Here is what I have done:

- Installed  xcode with command line utilities
- Installed MacPorts
- Installed and Compiled gnuradio with issuing 'sudo port install gnuradio' (it will take all night long)
- Installed and Compiled manually rtl-sdr
- Installed and Compiled manually gr-baz (I changed the 'bootstrap' script on line 28 from 'libtoolize --automake -c -f' to 'glibtoolize --automake -c -f'
- Copied the files inside gr-baz/grc to ~/.grc_gnuradio/
- Run the following command: export PYTHONPATH=$PYTHONPATH:/opt/local/lib/python2.6/site-packages:/opt/local/Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/:/usr/local/lib/python2.7/site-packages/

Remember the last step for all future Terminal sessions!

Arguments

Usage: borip_server.py: [options] <server address>

Options:
  -h, --help            show this help message and exit
  -l LISTEN, --listen=LISTEN
                        server listen port
  -p PORT, --port=PORT  default data port
  -v, --verbose         verbose output
  -g, --debug           debug output
  -c, --command         command output
  -r, --realtime        realtime scheduling
  -R, --no-reload       disable dynamic reload
  -d DEVICE, --device=DEVICE
                        immediately create device
  -L, --lock            lock device
  -D DEFAULT, --default=DEFAULT
                        device to create when default hint supplied

Notes on Included Device Flowgraphs

The following titles are the names of the GRC flowgraphs (not the generated Python file).

borip-USRP-Legacy

This uses my patched version of the Legacy USRP Source which outputs status messages (i.e. uO overruns, etc).

If you wish to use this with the original (un-patched) version, load the GRC file, and turn the Accept status property Off in the UDP Sink. Otherwise you will get a complaint about setting up a message queue at device creation.

Make sure that the 'unit' Parameter is first in the __init__ constructor if you re-generate the file!

borip-RTL

Only three supported arguments currently: tuner, readlen & buf.

borip_block-RTL

Only three supported arguments currently: tuner, readlen & buf.

Remember: the generated file will be placed in ~/.grc_gnuradio/.

Extensibility

Please note that the architecture of this version means the above main Python server program does not contain any native hardware interfaces (like the Windows version). It dynamically loads separate Python modules at runtime (e.g. GNU Radio flowgraphs) that provide access to hardware receivers, based on the Device Hint supplied at the client.

If you wish to add your own interfaces to access other hardware, you may:

• Write your own, and implement the Device and NetworkTransport classes (see class interfaces in apps/borip_server.py
• Create a GNU Radio flowgraph (e.g. in GR Companion), generate the Python code, and the server will automatically load it using a wrapper to make it look like the above classes. The name in the GRC Options block should be the same as the Device Hint you intend to use.

Note: the second method requires you have GNU Radio installed!

Dynamic Loading

Place Python files in locations where they will be picked up by Python (e.g. the apps directory). You can also add paths to the PYTHONPATH environement variable.

The server will load files in the following manner:

• Call the 'device hint mapper' function with the Device Hint from the connected client, and see if it returns a name
• If no name is returned, then use the first (non-whitespace) part of the Device Hint as the name

The server will then attempt to import the following Python module (file):

borip_<name>

Certain Device Hints (e.g. Legacy USRP device index, UHD Device Hint) are not suitable for direct use in a file name, which is where the 'device hint mapper' is used.

The default function is:

def _default_device_hint_mapper(hint):
    if hint is None or len(hint) == 0 or hint == "-":
        return "usrp_uhd"
    parts = hint.split(" ")
    try:
        idx = int(parts[0])
        return "usrp_legacy"
    except:
        pass
    try:
        kv = parts[0].index('=')    # key=value
        return "usrp_uhd"
    except:
        pass
    return parts[0].upper() # FCD, RTL

If you wish to create your own to support other devices, you can:

• edit this code directly, or (preferably):
• create another Python file called borip_server_devmap which will be imported on startup.

borip_server_devmap should contain a function called device_hint_mapper that should conform to the same interface as _default_device_hint_mapper above (take a string, and return one).

IMPORTANT: If you are creating Hierarchical Blocks, GRC will place the generated Python code in this directory:

~/.grc_gnuradio/

For the server to pick up files in this path, you could do something like:

export PYTHONPATH=~/.grc_gnuradio/

REMEMBER: You must set the name of the generated file in the Options block in GRC! Otherwise it will just end up 'top_block' and will not be picked-up by the server!

GNU Radio Flowgraph Wrapper

The wrapper will attempt to find 'helpers' in the flowgraph to fill in the information it needs. Helpers are Python attributes that are either normal (value) variables, or functions. You can create a 'function' variable easily in GRC by using the Variable block and entering a lambda function as the value.

The search order for helpers is:

1. the local flowgraph object
2. the local source (the GRC block, and therefore variable, should be called source)
3. the local flowgraph's parent (when a Hierarchical Block is loaded by the ServerWrapper class)

Please see the GnuRadioDevice implementation of the Device class to see which helpers are sought after by which functions, and in what order.

The list so far is:

source_name, name (for 'name', try local source first)
serial, serial_number
gain_range
master_clock
samples_per_packet, recv_samples_per_packet
antennas
set_gain
gain
set_samp_rate, set_sample_rate
samp_rate, sample_rate
set_freq, set_frequency
freq, frequency
was_tune_successful, was_tuning_successful
tune_tolerance, tuning_tolerance
last_tune_result
set_antenna
antenna

GRC Parameter blocks introduce variables to the __init__ constructor of the flowgraph. These will be filled in by additional arguments on the Device Hint. However only those Parameters that exist will be accepted during instantiation of the generated Python class!

If you are creating a Hierarchical Block, and wish to output status messages from the source block, you can use the Message Callback in dummy mode (and the Variable value set to '0'). The Message Callback won't actually call a function - it is just there so the BorIP server can get a handle on the message queue that GRC generates for it.

Self-contained Server in BorIP Sink

This will start the server internally, but external devices will not be created. Any Device Hint from a client will be ignored.

To prevent the sample rate being changed (i.e. stop the client from changing the samp_rate variable), create two Variable blocks:

• sample_rate

lambda: self.samp_rate

• set_sample_rate

lambda f: self.samp_rate

To set the number of samples transmitted in each packet, create a samples_per_packet Variable and set its value (this will set the payload size of the internal BorIP-enhanced UDP Sink block).

IMPORTANT: Remember to set the value of the BorIP Sink's Contant Multiplier property to ensure a normalised floating-point sample stream ([-1, +1]) is expanded to the range of a 16-bit signed integer ([-32768, +32767]), otherwise you won't get anything useful at the client!