Difference between revisions of "BorIP"

From SpenchWiki
Jump to: navigation, search
(→‎Client Protocol)
m (→‎Example)
Line 159: Line 159:
 
=== Example ===
 
=== Example ===
  
−
Example (colour coding: <span style="color:red">sent to client</span>, <span style="color:green">sent to server</span>):
+
Example (colour coding: <span style="color:green">sent to client</span>, <span style="color:blue">sent to server</span>):
 
  <span style="color:red">DEVICE -</span>
 
  <span style="color:red">DEVICE -</span>
 
  <span style="color:green">DEVICE 0</span>
 
  <span style="color:green">DEVICE 0</span>

Revision as of 16:38, 22 July 2011

Command-line arguments

  • Prepended with either / or -
    • port - set port to listen on (28888 by default)
    • device - supply without parameter to automatically create default UHD device, or give hint to specify which device to create
  • If you wish to apply these at Autorun time, append them to the registry key at:
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run\BorIP

Notes

  • Server limitations:
    • Only serves one client at a time. If an existing connection exists, other connections are disconnected (see Protocol for automatic BUSY response in this case).
    • Only connects to one device at a time.
    • Only sends baseband data to one UDP destination (no multiple destinations/broadcast/multicast... yet).
  • Cannot disconnect device once it has been 'created' in server. This will cause the server to crash (can't help this).

USB Driver Installation

Please refer to the USRP Zadig page.

Device creation (hint)

USRP

The hint is used to specify which device to create, and implies whether the UHD or Legacy interface is used:

  • A blank hint implies the default device, which depends on whether you are connecting to a local device, or a remote server:
    • For a local device, this means the default device that UHD will find.
    • For a remote server...
      ...that is not connected to a device, this also means the default UHD device
      ...this is already connected to a device, use that device.
  • Entering a hyphen ("-") will force a remote server to connect to the default UHD device, regardless of whether it is already connected to a device. Using it for a local device is the equivalent of leaving the hint blank.
  • To select the Legacy host interface, the following format must be used:
<device index> [sub-device[:side]] [FPGA image] [Firmware image]
  • Argument breakdown:
    • device index: a single digit (required, use 0 for the default Legacy device)
    • sub-device: a single digit, or single letter A-Z (e.g. B for USRP 1's B side)
    • side: a single digit, single letter A-Z, or AB (e.g. AB for BasicRX/LFRX)
    • FPGA image path: path (default is the Legacy default, usually std_2rxhb_2tx.rbf)
    • Firmware image path: path (default is the Legacy default, usually std.ihx)
  • Anything else is fed through to the UHD device factory (see UHD Device Identification Notes).
    • To supply a sub-device specification, simply follow the above sub-device/side format and append it to the comma-separated hint list - with the follow exception: it must conform to the UHD sub-device specification (e.g. the sub-device must be a letter, see UHD USRP 1 Application Notes).
    For example, to select the first available USRP 1 (assuming you also have other models of USRP connected) and use its B-side WBX daughterboard:
type=usrp1, B:0

FUNcube Dongle

FCD [<device index> [<I offset> [ [<gain offset> [<phase offset>]]]]] [mixergain={4,12}] [ifgain1={-3,6}]
  • Argument breakdown:
    • FCD is mandatory to select a FUNcube Dongle
    • If multiple dongles are connected, use an integer to specify the device index.
    • The offsets are expressed the same as in the FCHID application. If they are not supplied, the device's offsets will remain as they are.
    • The named key/value argument pairs can be specified in any order throughout the hint. If you wish to specify the offsets out of order, then you can also use the following key/value arguments keys: i=, q=, gain=, phase=.
      For example, to select the second FCD and set the offsets:
FCD 1 0.00156 0.00076 0.97586 0 mixergain=4 ifgain1=-3

RTL2832U-based DVB-T USB Dongle

RTL <options>

Please see the USRP Interfaces for all options.

Additional considerations & limitations

  • The clients and BorIP protocol are currently limited to complex short sample pairs
    • 2 x 16-bit samples = 4 bytes per complex sample
  • The supported frequency range of hardware is not currently checked. However, the success of a tune request is checked.
    • So for the moment, if you have a WBX for example, you will see tune requests succeed that are slightly outside the spec'ed range of the daughterboard.
  • Since the Legacy interface does not support querying what antennas are available on a specific daughterboard, it will always return the following list of possibilities:
    • TX/RX, RX2, RXA, RXB, RXAB
  • Both UHD and Legacy client ask from the host API what the FPGA clock rate is (i.e. 64MHz is not hardcoded in the client). However it may be hardcoded in the host layer (e.g. IIRC it is in Legacy), so if you are clocking your USRP at a different rate there are two options:
    1. Stick to UHD
    2. Let me know and I'll add an option that will override the clock rate

Client Protocol

Overview

  • Simple ASCII-encoded text requests and responses.
  • Each request is given a response (so one request/response pair at a time, no batching).

Connection

  • Upon successful connection, the server will automatically send a DEVICE response (see below).
  • If the server is already in use (i.e. an existing connection exists), the following string will be sent to the new client and then the connection will be terminated:
BUSY<LF>
  • The destination for baseband data packets will be reset to the address of the connected client, and the port will be reset to 28888 (the default).
  • Baseband BorIP UDP packet headers are re-enabled if they were disabled in the previous session.

Disconnection

  • If a device is currently created, it will remain active (i.e. it is not automatically release on disconnection).

Format

  • Request format (COMMAND is case-insensitive):
<COMMAND> [<PARAMETERS>]<CR, LF or CRLF>
  • If a request is given...
    ...with parameters, it implies an action (i.e. the server should do something), and the success of the action (with any command-specific results) will be returned to the client. The exceptions are the DEVICE, GO and STOP commands.
    ...without parameters, it implies a state query of the server, and the requested state's value will be returned (there will be no indication of success or failure - this is implied in the returned value).
  • Response format (COMMAND is always UPPERCASE version that in previous request):
<COMMAND> [<SUCCESS>] [<COMMAND-SPECIFIC RESULT>]<LF>
  • Colour coding:
Request parameters
Success
An error

Generic action results

  • The following are the possible values of SUCCESS when a request is submitted with parameters:
OK      - Request was processed succesfully, and there is no further data
FAIL    - Request was processed, but an error occurred
UNKNOWN - Unknown command
DEVICE  - Request assumes a device is connected & created, but this is not the case
  • There are some command-specific results not listed here, which are described below in the relevant section.

Commands & responses

DEVICE
  • The response version of this command is automatically sent when a client connects to an available server.

Parameters: 

-      Create default UHD device
!      Release current device
<hint> See Device Hint specification

Response (this not not conform to the standard format as the SUCCESS field is never sent): 

- (a hyphen) No device has been created, which is:
                an indication that no device is created (when a client first connects)
                a failure response to attempted device creation
<DEVICE SERIAL>|<MIN GAIN>|<MAX GAIN>|<GAIN STEP>|<FPGA FREQ IN HZ>|<SAMPLES PER PACKET>|<CSV LIST OF VALID ANTENNAS>

A SAMPLE is defined as a complex sample pair (I & Q).

FREQ

Single parameter for action request: 

<FREQUENCY IN HZ> - Frequency to tune to

Additional possible action request-specific success values: 

LOW  - Too low for hardware
HIGH - Too high for hardware

Additional possible action request-specific results (when success is OK): 

<TARGET IF IN HZ> <ACTUAL IF IN HZ> <TARGET DDC IN HZ> <ACTUAL DDC IN HZ>
     - Tune result as per UHD tune_result_t

Additional query request result (i.e. no request parameters): 

<FREQUENCY IN HZ> - Frequency hardware is tuned to, or last frequency that was requested if host host interface does not support querying current tuner frequency
ANTENNA

Single parameter for action request: 

<ANTENNA NAME> - Name of antenna to select

Additional query request result (i.e. no request parameters): 

<ANTENNA NAME> - Currently selected antenna, or last antenna that was requested if interface does not support querying current antenna
UNKNOWN - Host interface did not return an antenna
RATE

Single parameter for action request: 

<SAMPLE RATE IN SAMPLES PER SECOND> - New rate to sample at

Additional query request result (i.e. no request parameters): 

<SAMPLE RATE IN SAMPLES PER SECOND> - Current sampling rate, or last rate that was requested if host interface does not support querying current rate
GAIN

Single parameter for action request: 

<GAIN IN RANGE FROM DEVICE RESPONSE> - New gain/attenuation to set

Additional query request result (i.e. no request parameters): 

<GAIN IN RANGE FROM DEVICE RESPONSE> - Current gain, or last gain that was requested if host interface does not support querying current gain
DEST

Single parameter for action request: 

<IP ADDRESS>[<:PORT NUMBER>] - IP address and optional port where baseband UDP packets will be streamed

Additional query request result (i.e. no request parameters): 

<IP ADDRESS>:<PORT NUMBER> - IP address and optional port where baseband UDP packets will be streamed
HEADER
  • BorIP packet headers are enabled by default
  • Enable for clients that expect them, e.g. ExtIO USRP
  • Disable for clients that don't expect them, e.g. UDP Source block in GNU Radio/GRC

Single parameter for action request: 

<ON|OFF> - Set whether BorIP packet headers are included in streaming UDP packets

Additional query request result (i.e. no request parameters): 

<ON|OFF> - Whether BorIP packet headers will be included in streaming UDP packets
GO and STOP
  • Start and stop streaming baseband data to the pre-request destination (by default this is the client, on port 28888).
  • Neither commands take parameters.
  • In addition to the OK and FAILED success values, the following are also possible for GO and STOP respectively:
RUNNING - Already streaming data
STOPPED - Already stopped streaming data

Example

Example (colour coding: sent to client, sent to server): 

DEVICE -
DEVICE 0
DEVICE 4c69abc2|0.000000|50.500000|0.500000|64000000.000000|4096|TX/RX,RX2
FREQ 123456789
FREQ OK 123456789.000000 123456735.500000 -53.504831 -53.500000
GAIN 25
GAIN OK
RATE 1000000
RATE OK 1000000.000
DEST 192.168.1.1
DEST OK
ANTENNA RX2
ANTENNA OK
GO
GO OK
STOP
STOP OK
DEVICE !
DEVICE -

Bugs

  • On first creation of Legacy device, serial will fail to be fetched correctly (will remain blank), but device will still work.
    • If application is restarted while programmed USRP remains connected, creation of Legacy device will result in serial now being displayed.
  • Cannot start program, then connect Legacy device, then attempt to create
    • Must connect USRP first, then start program
  • Legacy is more efficient in this compilation than UHD at higher sampling rates

To Do

  • (Detect changes in power state and release device to prevent app crash when resuming.)
    • Apparently it still works if device is left connected and powered on.
  • Announce via Bounjour/custom broadcast
  • Ability to set up multiple streams
  • Buffer & request re-send of section that was dropped (e.g. lost packets)
Retrieved from "http://wiki.spench.net/index.php?title=BorIP&oldid=392"