PyRF Documentation¶
Overview¶
PyRF is an openly available, comprehensive development environment for wireless signal analysis. PyRF handles the low-level details of configuring a device, real-time data acquisition and signal processing, allowing you to concentrate on your analysis solutions. Hence, it enables rapid development of powerful applications that leverage the new generation of measurement-grade software-defined radio technology, such as ThinkRF Real-Time Spectrum Analysis Software.
PyRF is built on the Python Programming Language (v2.7) and includes feature-rich libraries, examples including visualization applications and source code, all specific to the requirements of signal analysis. It is openly available, allowing commercialization of solutions through BSD open licensing and offering device independence via standard hardware APIs.
Table of Contents¶
Manual¶
Installation¶
This section provides information on how to install the required python packages.
Note: Python v2.7.x is the required version for PyRF, not v3.x or higher.
Windows Setup¶
1. Set-up Python v2.7
- Install Python v2.7 from https://www.python.org/downloads/release/python-2715/
- Add to the windows PATH: C:\Python27 and C:\Python27\Scripts
2. Install Dependencies
These installation steps make use of pip software to install required libraries. Open a command prompt window and type pip, if a help menu appears, pip is already in your system. If pip has not yet been installed, follow these instructions:
Download get-pip.py (right mouse click and save)
Open a command prompt window, navigate to get-pip.py and run:
python get-pip.pyNow use pip to install the dependencies by typing into the command prompt window:
pip install numpy scipy pyside==1.2.2 pyqtgraph twisted zope.interface setuptools pywin32 pip install netifaces
- Notes:
- pySide v1.2.2 is needed, not the latest
- When installing netifaces, MS Visual C++ 9.0 is required, follow the recommended instruction, such as
error: Microsoft Visual C++ 9.0 is required. Get it from http://aka.ms/vcpython27
- To install qtreactor, choose one of the following option:
If you have git, run:
pip install -e git://github.com/pyrf/qtreactor.git#egg=qtreactorOtherwise, download qtreactor-pyrf-1.0 to your computer, unzip and then go into the extracted folder in a command prompt window and type:
python setup.py installContinue with PyRF Installation below.
Linux Setup¶
These instructions are tested on Debian/Ubuntu system, equivalent apt-get command might be needed for your system.
Install python2.7 package if not already available in your system
Install required libraries (sudo privilege might be needed):
apt-get install pip pip install numpy scipy pyside==1.2.2 pyqtgraph twisted netifaces zope.interface setuptools pip install -e git://github.com/pyrf/qtreactor.git#egg=qtreactorOr install dependencies from source:
apt-get install qt-sdk python-dev cmake libblas-dev libatlas-dev liblapack-dev gfortran export BLAS=/usr/lib/libblas/libblas.so export ATLAS=/usr/lib/atlas-base/libatlas.so export LAPACK=/usr/lib/lapack/liblapack.so pip install -r requirements.txt pip install pyside==1.2.2Continue with PyRF Installation below.
PyRF Installation¶
- Download the development version by either:
Using git and run:
git clone git://github.com/pyrf/pyrf.gitOr download a stable release here and extract
Navigate to pyrf directory (
cd pyrf
), run:python setup.py installPyRF API for ThinkRF RTSA Products¶
pyrf.devices.thinkrf.WSA
is the class that provides access to ThinkRF Real-Time Spectrum Analyzers (RTSA, also formerly known as WSA) devices. Its methods closely match the SCPI Command Set described in the product’s Programmer’s Guide (available on ThinkRF Resources).There are simple examples illustrating usage of this API under the examples directory included with the source code directory. Some are mentioned in the Examples section of this document .
This API may be used in a blocking mode (the default) or in an asynchronous mode with using the Twisted python library.
In blocking mode, all methods that read from the device will wait to receive a response before returning.
In asynchronous mode, all methods will send their commands to the device and then immediately return a Twisted Deferred object. If you need to wait for the response or completion of this command, you can attach a callback to the Deferred object and the Twisted reactor will call it when ready. You may choose to use Twisted’s
inlineCallbacks
function decorator to write Twisted code that resembles synchronous code by yielding the Deferred objects returned from the API.To use the asynchronous, when a WSA instance of a device (ex.
dut = WSA()
) is created, you must pass apyrf.connectors.twisted_async.TwistedConnector
instance as the connector parameter, as shown in discovery.py / twisted_discovery.pyReference¶
pyrf.devices¶
.thinkrf¶
- class
pyrf.devices.thinkrf.
WSA
(connector=None)¶Interface for ThinkRF’s R5500, R5700, and WSA5000 (EOL).
Parameters: connector – Connector object to use for SCPI/VRT connections, defaults to a new PlainSocketConnector
instance
connect()
must be called before other methods are used.Note
The following methods will either block then return a result or if you passed a
TwistedConnector
instance to the constructor, they will immediately return a Twisted Deferred object.The methods are grouped and listed by functionalities.
Connection Related Methods:
connect
(host)¶Connect to an RTSA (aka WSA).
Parameters: host (str) – the hostname or IP to connect to Usage:
dut.connect('123.456.789.1')
disconnect
()¶Close a connection to an RTSA (aka WSA).
async_connector
()¶Return True if the connector being used is asynchronous
set_async_callback
(callback)¶Set the asynchronous callback for a function when the device receives a VRT packet. Use with Twisted setup. :param callback: callback to set. Set to None to disable receiving packets.
Direct SCPI commands:
scpiget
(cmd)¶Send a SCPI query command and wait for the response.
This is the lowest-level interface provided. See the product’s Programmer’s Guide for the SCPI commands available.
Parameters: cmd (str) – the SCPI command to send Returns: the response output from the box if any
scpiset
(cmd)¶Send a SCPI command of set type (i.e. not query command).
This is the lowest-level interface provided. See the product’s Programmer’s Guide for the SCPI commands available.
Parameters: cmd (str) – the command to send
errors
()¶Flush and return the list of errors from past commands sent to the RTSA. An empty list is returned when no errors are present.
Device System Related:
id
()¶Returns the RTSA’s identification information string.
Returns: “<Manufacturer>,<Model>,<Serial number>,<Firmware version>”
reset
()¶Resets the RTSA to its default configuration. It does not affect the registers or queues associated with the IEEE mandated commands.
locked
(modulestr)¶This command queries the lock status of the RF VCO (Voltage Control Oscillator) in the Radio Front End (RFE) or the lock status of the PLL reference clock in the digitizer card.
Parameters: modulestr (str) – ‘VCO’ for rf lock status, ‘CLKREF’ for ref clock lock status Returns: True if locked Data Acquisition Related Methods:
- Get permission:
has_data
()¶Check if there is VRT data to read.
Returns: True if there is a packet to read, False if not
request_read_perm
()¶Acquire exclusive permission to read data from the RTSA.
Returns: True if allowed to read, False if not
have_read_perm
()¶Check if we have permission to read data from the RTSA.
Returns: True if allowed to read, False if not
- Set capture size for stream or block mode capture:
ppb
(packets=None)¶This command sets the number of IQ packets in a capture block
Parameters: packets (int) – the number of packets for a block of capture, or None to query Returns: the current ppb value if the packets parameter is None
spp
(samples=None)¶This command sets or queries the number of Samples Per [VRT] Packet (SPP).
The upper bound of the samples is limited by the VRT’s 16-bit packet size field. However, since the SPP must be a multiple of 32, the maximum is thus limited by (2**16 - 32) or 65504.
Parameters: samples (int) – the number of samples in a VRT packet (256 to 65504, a multiple of 32), or None to query Returns: the current spp value if the samples parameter is None
- Stream setup
stream_status
()¶This query returns the current running status of the stream capture mode.
Returns: ‘RUNNING’ or ‘STOPPED’
stream_start
(stream_id=None)¶This command begins the execution of the stream capture. It will also initiate data capturing. Data packets will be streamed (or pushed) from the RTSA whenever data is available.
Parameters: stream_id (int) – optional unsigned 32-bit stream identifier
- Sweep setup:
sweep_add
(entry)¶Add a sweep entry to the sweep list
Parameters: entry (pyrf.sweepDevice.sweepSettings) – the sweep entry settings to add to the list
sweep_clear
()¶Remove all entries from the sweep list.
sweep_iterations
(count=None)¶Set or query the number of iterations to loop through a sweep list.
Parameters: count (int) – the number of iterations, 0 for infinite, or None to query Returns: the current number of iterations if count is None
sweep_read
(index)¶Read a sweep entry at the given sweep index from the sweep list.
Parameters: index – the index of the entry to read Returns: settings of that sweep entry Return type: pyrf.config.SweepEntry
sweep_start
(start_id=None)¶Start the sweep engine with an optional ID.
Parameters: start_id (int) – An optional 32-bit ID to identify the sweep
- VRT data acquisition related methods:
capture
(spp, ppb)¶This command will start the single block capture of ppb packets of spp samples in each packet. The data within a single block capture trace is continuous from one packet to the other, but not necessary between successive block capture commands issued. Used for stream or block capture mode. To read data back, use
read()
method. See show_i_q.py as an example.
Parameters:
- spp (int) – the number of samples in a VRT packet
- ppb (int) – the number of packets in a block of capture
capture_mode
()¶This command queries the current capture mode
Returns: the current capture mode
raw_read
(num)¶Raw read of VRT socket data of num bytes from the RTSA.
Parameters: num (int) – the number of bytes to read Returns: bytes
read
()¶Read and return a single parsed VRT packet from the RTSA, either context or data.
read_data
(spp)¶Read and return a data packet, as well as computed power spectral density data, of spp (samples per packet) size, the associated context info and the computed power spetral data. If a block of data is requested (such as ppb is more than 1), loop through this function to retreive all data. See also data other capture functions:
pyrf.util.capture_spectrum()
,pyrf.capture_device.capture_time_domain()
Parameters: spp (int) – the number of samples in a VRT packet (256 to 65504) in a multiple of 32 Returns: data, context dictionary, and power spectral data array
abort
()¶This command will cause the RTSA to stop the data capturing, whether in the manual trace block capture, triggering or sweeping mode. The RTSA will be put into the manual mode; in other words, process such as streaming, trigger and sweep will be stopped. The capturing process does not wait until the end of a packet to stop, it will stop immediately upon receiving the command.
flush
()¶This command clears the RTSA’s internal data storage buffer of any data that is waiting to be sent. Thus, it is recommended that the flush command should be used when switching between different capture modes to clear up the remnants of captured packets.
eof
()¶Check if the VRT stream has closed.
Returns: True if no more data, False if more data Device Configuration Methods for Non-Sweep Setup:
attenuator
(atten_val=None)¶This command enables, disables or queries the RTSA’s RFE attenuation.
Parameters: atten_val – see Programmer’s Guide for the attenuation value to use for your product; None to query Returns: the current attenuation value if None is used
decimation
(value=None)¶This command sets or queries the rate of decimation of samples in a trace capture. The supported rate is 4 - 1024. When the rate is set to 1, no decimation is performed on the trace capture.
Parameters: value (int) – new decimation value (1 or 4 - 1024); None to query Returns: the decimation value if None is used
freq
(freq=None)¶This command sets or queries the tuned center frequency of the RTSA.
Parameters: freq (int) – the center frequency in Hz (range vary depnding on the product model); None to query Returns: the frequency in Hz if None is used
fshift
(shift=None)¶This command sets or queries the frequency shift value.
Parameters: freq (int) – the frequency shift in Hz (0 - 125 MHz); None to query Returns: the amount of frequency shift if None is used
hdr_gain
(gain=None)¶This command sets or queries the HDR gain of the receiver. The gain has a range of -10 to 30 dB.
Parameters: gain (int) – float between -10 and 30 to set; None to query Returns: the hdr gain in dB if None is used
iq_output_path
(path=None)¶This command sets or queries the RTSA’s current IQ path. It is not applicable to R5700.
Parameters: path (str) – ‘DIGITIZER’, ‘CONNECTOR’, ‘HIF’, or None to query Returns: the current IQ output path type if None is used
pll_reference
(src=None)¶This command sets or queries the RTSA’s PLL reference source
Parameters: src (str) – ‘INT’, ‘EXT’, ‘GPS’ (when available with the model) or None to query Returns: the current PLL reference source if None is used
psfm_gain
(gain=None)¶This command sets or queries one of the Pre-Select Filter Modules’s (PSFM) gain stages.
Parameters: gain (str) – sets the gain value to ‘high’, ‘medium’, ‘low’, or None to query Returns: the RF gain value if None is used Usage:
dut.psfm_gain('HIGH')
rfe_mode
(mode=None)¶This command sets or queries the RTSA’s Receiver Front End (RFE) mode of operation.
Parameters: mode (str) – ‘ZIF’, ‘DD’, ‘HDR’, ‘SHN’, ‘SH’, or None to query Returns: the current RFE mode if None is used
trigger
(settings=None)¶This command sets or queries the type of trigger event. Setting the trigger type to “NONE” is equivalent to disabling the trigger execution; setting to any other type will enable the trigger engine.
Parameters: settings (dictionary) – the new trigger settings; None to query Returns: the trigger settings if None is used
apply_device_settings
(settings, force_change=False)¶This command takes a dict of device settings, and applies them to the RTSA
Parameters:
- settings (dict) – dict containing device’s settings such as attenuation, decimation, etc
- force_change (bool) – to force the change update or not
DSP and Data Processing Related Methods:
measure_noisefloor
(rbw=None, average=1)¶Returns a power level that represents the top edge of the noisefloor
Parameters:
- rbw (int) – rbw of spectral capture (Hz) (will round to nearest native RBW) or None
- average (int) – number of capture iterations
Returns: noise_power
peakfind
(n=1, rbw=None, average=1)¶Returns frequency and the power level of the maximum spectral point computed using the current settings, Note this function disables
Parameters:
- n (int) – determine the number of peaks to return
- rbw (int) – rbw of spectral capture (Hz) (will round to nearest native RBW) or None
- average (int) – number of capture iterations
Returns: [(peak_freq1, peak_power1), (peak_freq2, peak_power2) , …, (peak_freqn, peak_powern)]
Data Recording Related Methods:
Device Discovery Functions:
pyrf.devices.thinkrf.
discover_wsa
(wait_time=0.125)¶
pyrf.devices.thinkrf.
parse_discovery_response
(response)¶This function parses the RTSA’s raw discovery response
Parameters: response – The RTSA’s raw response to a discovery query Returns: Return (model, serial, firmware version) based on a discovery response message pyrf.connectors¶
.blocking¶
- class
pyrf.connectors.blocking.
PlainSocketConnector
¶This connector makes SCPI/VRT socket connections using plain sockets, of blocking type.
pyrf.connectors.blocking.
socketread
(socket, count, flags=None)¶Retry socket read until count amount of data received, like reading from a file.
Parameters:
- count (int) – the amount of data received
- flags – socket.recv() related flags
.twisted_async¶
- class
pyrf.connectors.twisted_async.
TwistedConnector
(reactor, vrt_callback=None)¶A connector that makes SCPI/VRT connections asynchronously using Twisted method.
Parameters:
- reactor – a twisted reactor, (ex: “from twisted.internet import reactor”)
- vrt_callback (callback) – A callback may be assigned to vrt_callback that will be called with VRT packets as they arrive. When vrt_callback is None (the default), arriving packets will be ignored.
- exception
pyrf.connectors.twisted_async.
TwistedConnectorError
¶
- class
pyrf.connectors.twisted_async.
VRTClient
(receive_callback)¶A Twisted protocol for the VRT connection.
Parameters: receive_callback – a function that will be passed a vrt DataPacket or ContextPacket when it is received pyrf.capture_device¶
- class
pyrf.capture_device.
CaptureDevice
(real_device, async_callback=None, device_settings=None)¶Virtual device that returns power levels generated from a single data packet
Parameters:
- real_device – the device that will be used for capturing data, typically a
pyrf.thinkrf.WSA
instance.- async_callback – callback to use for async operation (not used if real_device is using a blocking
PlainSocketConnector
)- device_settings – initial device settings to use, passed to
pyrf.capture_dvice.CaptureDevice.configure_device()
if given
capture_time_domain
(rfe_mode, freq, rbw, device_settings=None, min_points=256, force_change=False)¶Initiate a capture of raw time domain IQ or I-only data
Parameters:
- rfe_mode (str) – radio front end mode, e.g. ‘ZIF’, ‘SH’, …
- freq (int) – center frequency in Hz to set
- rbw (float) – the resolution bandwidth (RBW) in Hz of the data to be captured (output RBW may be smaller than requested)
- device_settings (dict or None) – rfe_mode, freq, decimation, fshift and other device settings
- min_points (int) – smallest number of data points per capture from the device
- force_change (bool) – force the configuration to apply device_settings changes or not
Returns: (fstart, fstop, data) where fstart & fstop are frequencies in Hz & data is a list
configure_device
(device_settings, force_change=False)¶Configure the device settings on the next capture
Parameters:
- device_settings (dict) – rfe mode, attenuation, decimation and other device settings
- force_change (bool) – force the configuration to apply device_settings changes or not
- exception
pyrf.capture_device.
CaptureDeviceError
¶pyrf.sweep_device¶
- class
pyrf.sweep_device.
SweepDevice
(real_device, async_callback=None)¶Virtual device that generates power spectrum from a given frequency range by sweeping the frequencies with a real device and piecing together the FFT results.
Parameters:
- real_device – the RF device that will be used for capturing data, typically a
pyrf.devices.thinkrf.WSA
instance.- async_callback – a callback to use for async operation (not used if real_device is using a blocking
PlainSocketConnector
)
capture_power_spectrum
(fstart, fstop, rbw, device_settings=None, mode='SH', continuous=False)¶Initiate a data capture from the real_device by setting up a sweep list and starting a single sweep, and then return power spectral density data along with the actual sweep start and stop frequencies set (which might not be exactly the same as the requested fstart and fstop).
Note
This function does not pipeline, and if the last sweep isn’t received before starting a new one, it will generate a failure.
Parameters:
- fstart (int) – sweep starting frequency in Hz
- fstop (int) – sweep ending frequency in Hz
- rbw (float) – the resolution bandwidth (RBW) in Hz of the data to be captured (output RBW may be smaller than requested)
- device_settings (dict) – attenuation and other device settings
- mode (str) – sweep mode, ‘ZIF’, ‘SH’, or ‘SHN’
- continuous (bool) – set sweep to be continuously or not (once only)
Returns: fstart, fstop, power_data
- exception
pyrf.sweep_device.
SweepDeviceError
¶Exception for the sweep device to state an error() has occured
- class
pyrf.sweep_device.
SweepPlanner
(dev_prop)¶An object that plans a sweep based on given paramaters.
Parameters: dev_prop (dict) – the sweep device properties
- class
pyrf.sweep_device.
SweepSettings
¶An object used to keep track of the sweep settings
pyrf.config¶
- class
pyrf.config.
SweepEntry
(fstart=2400000000, fstop=2400000000, fstep=100000000, fshift=0, decimation=0, gain='vlow', ifgain=0, hdr_gain=-10, spp=1024, ppb=1, trigtype='none', dwell_s=0, dwell_us=0, level_fstart=50000000, level_fstop=10000000000, level_amplitude=-100, attenuator=30, rfe_mode='SH')¶Sweep entry setup for
pyrf.devices.thinkrf.WSA.sweep_add()
Parameters:
- fstart (int) – starting frequency in Hz
- fstop (int) – ending frequency in Hz
- fstep (int) – frequency step in Hz
- fshift (int) – the frequency shift in Hz
- decimation (int) – the decimation value (0 or 4 - 1023)
- gain (str) – the RF gain value (‘high’, ‘medium’, ‘low’ or ‘vlow’)
- ifgain (int) –
the IF gain in dB (-10 - 34)
Note
parameter is deprecated, kept for a legacy device
- hdr_gain (int) – the HDR gain in dB (-10 - 30)
- spp (int) – samples per packet (256 - max, a multiple of 32) that fit in one VRT packet
- ppb (int) – data packets per block
- dwell_s (int) – dwell time seconds
- dwell_us (int) – dwell time microseconds
- trigtype (str) – trigger type (‘none’, ‘pulse’ or ‘level’)
- level_fstart (int) – level trigger starting frequency in Hz
- level_fstop (int) – level trigger ending frequency in Hz
- level_amplitude (float) – level trigger minimum in dBm
- attenuator – vary depending on the product
- rfe_mode (str) – RFE mode to be used, such as ‘SH’, ‘SHN’, ‘DD’, etc.
Returns: a string list of the sweep entry’s settings
- class
pyrf.config.
TriggerSettings
(trigtype='NONE', fstart=None, fstop=None, amplitude=None)¶Trigger settings for
pyrf.devices.thinkrf.WSA.trigger()
.
Parameters:
- trigtype (str) – “LEVEL”, “PULSE”, or “NONE” to disable
- fstart (int) – trigger starting frequency in Hz
- fstop (int) – trigger ending frequency in Hz
- amplitude (float) – minimum level for trigger in dBm
Returns: a string in the format: TriggerSettings(trigger type, fstart, fstop, amplitude)
- exception
pyrf.config.
TriggerSettingsError
¶Exception for the trigger settings to state an error() has occured
pyrf.numpy_util¶
pyrf.numpy_util.
calculate_channel_power
(power_spectrum)¶Return a dBm value representing the channel power of the input power spectrum.
Parameters: power_spectrum (list) – an array containing the power spectrum to be used for the channel power calculation Returns: the channel power result
pyrf.numpy_util.
calculate_occupied_bw
(pow_data, span, occupied_perc)¶Return the occupied bandwidth of a given spectrum, and occupied percentage
Parameters:
- pow_data (list) – spectral data to be analyzed
- span (int) – span of the given spectrum, in Hz
- occupied_perc (float) – Percentage of the power to be measured
Returns: float value of the occupied bandwidth
pyrf.numpy_util.
calibrate_time_domain
(power_spectrum, data_pkt)¶Return a list of the calibrated time domain data
Parameters:
- power_spectrum (list) – spectral data of the time domain data
- data_pkt (pyrf.vrt.DataPacket) – a RTSA VRT data packet
Returns: a list containing the calibrated time domain data
pyrf.numpy_util.
compute_fft
(dut, data_pkt, context, correct_phase=True, iq_correction_wideband=True, hide_differential_dc_offset=True, convert_to_dbm=True, apply_window=True, apply_spec_inv=True, apply_reference=True, ref=None, decimation=1)¶Return an array of dBm values by computing the FFT of the passed data and reference level.
Parameters:
- dut (pyrf.devices.thinkrf.WSA) – WSA device
- data_pkt (pyrf.vrt.DataPacket) – packet containing samples
- context (dict) – context values, such as ‘bandwidth’, ‘reflevel’, etc.
- correct_phase (bool) – apply phase correction for captures with IQ data or not
- iq_correction_wideband (bool) – apply wideband IQ correction or not
- hide_differential_dc_offset (bool) – mask the differential DC offset present in captures with IQ data or not
- convert_to_dbm (bool) – convert the output values to dBm or not
- apply_window (bool) – apply windowing to FFT function or not
- apply_spec_inv (bool) – apply spectral inversion to the FFT bin or not. Recommend to leave as default
- apply_reference (bool) – apply reference level correction or not
- ref (float) – a reference value to apply to the noise level
- decimation (int) – the decimation value (1, 4 - 1024)
Returns: numpy array of spectral data in dBm, as floats
pyrf.util¶
pyrf.util.
capture_spectrum
(dut, rbw=None, average=1, dec=1, fshift=0)¶Returns the spectral data, and the usable start and stop frequencies corresponding to the RTSA’s current configuration
Parameters:
- rbw (int) – rbw of spectral capture (Hz) (will round to nearest native RBW)
- average (int) – number of capture iterations
- dec (int) – decimation factor applied
- fshift (int) – the fshift applied, in Hz
Returns: (fstart, fstop, pow_data) where pow_data is a list
pyrf.util.
read_data_and_context
(dut, points=1024)¶Initiate capture of one VRT data packet, wait for and return data packet and collect preceeding context packets.
Parameters: points (int) – Number of data points to capture Returns: (data_pkt, context_values) Where context_values is a dict of {field_name: value} items from all the context packets received.
pyrf.vrt¶
- class
pyrf.vrt.
ContextPacket
(packet_type, count, size, tmpstr, has_timestamp)¶A Context Packet received from
pyrf.devices.thinkrf.WSA.read()
. See VRT section of the product’s Programmer’s Guide for more information.
Parameters:
- packet_type – VRT packet type
- count – VRT packet counter (see VRT protocol)
- size (int) – The VRT packet size, less headers and trailer words
- tmpstr – hold the raw data for parsing
- has_timestamp (bool) – to indicate timestamp is available with the packet
fields
¶a dict containing field names and values from the packet
is_context_packet
(ptype=None)¶
Parameters: ptype (str) – “Receiver”, “Digitizer” or None for any packet type Returns: True if this packet matches the ptype passed
is_data_packet
()¶To indicate this VRT packet is not of data type as it’s a ContextPacket
Returns: False
- class
pyrf.vrt.
DataPacket
(count, size, stream_id, tsi, tsf, payload, trailer)¶A Data Packet received from
pyrf.devices.thinkrf.WSA.read()
data
¶a
pyrf.vrt.IQData
object containing the packet data
is_context_packet
(ptype=None)¶
Returns: False
is_data_packet
()¶
Returns: True
- class
pyrf.vrt.
IQData
(binary_data)¶Data Packet values as a lazy collection of (I, Q) tuples read from binary_data.
This object behaves as an immutable python sequence, e.g. you may do any of the following:
points = len(iq_data) i_and_q = iq_data[5] for i, q in iq_data: print i, q
numpy_array
()¶Return a numpy array of I, Q values for this data
- exception
pyrf.vrt.
InvalidDataReceived
¶
pyrf.vrt.
vrt_packet_reader
(raw_read)¶Read a VRT packet, parse it and return an object with its data.
Implemented as a generator that yields the result of the passed raw_read function and accepts the value sent as its data.
Parameters: raw_read (list) – VRT packet of raw data (bytes) Examples¶
This section explains some of the examples included with the PyRF source code.
Typical Usage:
python <example_file>.py [device_IP_when_needed]discovery.py / twisted_discovery.py¶
These examples detect RTSA devices on the local network.
Example output:
R5700-427 180601-661 1.5.0 10.126.110.133 R5500-408 171212-007 1.5.0 10.126.110.123 R5500-418 180522-659 1.4.8 10.126.110.104show_i_q.py / twisted_show_i_q.py¶
These examples connect to a device of IP specified on the command line, tunes it to a center frequency of 2.450 MHz then reads and displays one capture of 1024 i, q values.
Example output (truncated):
0,-20 -8,-16 0,-24 -8,-12 0,-32 24,-24 32,-16 -12,-24 -20,0 12,-32 32,-4 0,12 -20,-16 -48,16 -12,12 0,-36 4,-12pyqtgraph_plot_single_capture.py / pyqtgraph_plot_block.py¶
These examples connect to a device of IP specified on the command line, tunes it to a center frequency, then continually capture and display the computed spectral data using pyqtgraph.
pyqtgraph_plot_sweep.py¶
This example connects to a device of IP specified on the command line, makes use of sweep_device.py to perform a single sweep entry monitoring and plots computed spectral results using pyqtgraph.
matplotlib_plot_sweep.py¶
This example connects to a device specified on the command line, and plots a large sweep of the spectrum using NumPy and matplotlib.
simple_gui¶
This folder contains a simple example on creating a GUI (using pyqtgraph along with Twisted) to plot real-time data acquired from ThinkRF’s RTSA device. It displays the spectral density data in the top plot, and the raw I &/or Q data (when available) in the lower plot.
Usage:
python run_gui.py <device_ip>Change Logs¶
PyRF 2.9.1¶
- Updated this PyRF Manual/Documentation
- Added more examples
PyRF 2.9.0¶
2018-10-12
- Added GNSS support for R5700 RTSA products including VRT GNSS context packet
- Added support for R5500 products
- Added flush and reset to capture setup
- Added calibrate_time_domain() function for a given time-domain data point
- Added calculate_occupied_bw() function for a given spectrum and occupied percentage
- Refactored sweep_device functions
- Restructured ThinkRF device properties and removed deprecated ones
- Improved IQ offset algorithm
- Enabled “100 kHz span” (HDR mode) for R5500 products
- Enabled trigger feature
- Changed Baseband (DD mode)’s MIN_TUNABLE to 32.25 MHz
- Changed R5500’s minimum frequency to 10 kHz
- Changed WSA5000’s minimum frequency to 100 kHz
- Changed minimum sample size for sweep to be 32
- Fixed zero-span setting
- Fixed bugs related to RBW setup
- Fixed bugs related sweep setup
- Fixed lock-up issue due to unexpected data packet received
- Fixed attenuation setting for R5500
- Fixed sample sizes being off by 32 samples
- Fixed capture_device bug related to number of data points
- Fixed bugs related to CSV file and settings
PyRF 2.8.0¶
2015-08-12
- Removed RTSA Instructions from the web page
- Fixed windows installation instructions
- Added capture spectrum function
- Added find peak function
- Added Measure noisefloor function
- Changed default span settings
- Added saturation level value for each device
PyRF 2.7.2¶
2014-12-16
- Added capture control widget
- Changed default save file names to represent date and time of capture
- Fixed baseband mode frequency axis issue
- Netifaces library is no longer a hard requirement
- Improved overall marker controls
- Added ‘Enable mouse tune’ option to frequency widget
- Default HDR gain is now 25
PyRF 2.7.1¶
2014-11-13
- Discovery widget now queries for new WSA’s on the network every 10 seconds
- Fixed issue where switching from sweep to non-sweep wrongly changed center frequency
- Fixed issue where Minimum control not behaving as designed
- Fixed issue where trigger controls were not disabled for non-trigger modes
- Fixed frequency axis texts
- Y-axis in the persistence plot now corresponds with spectral plot’s y-axis
PyRF 2.7.0¶
2014-11-04
- All control widgets are now dockable
- Enabled mouse control of spectral plot’s y-axis
- Added lower RBW values in non-sweep modes
PyRF 2.6.2¶
2014-10-10
- HDR gain control in GUI now allows values up to +20 dB
- Sweep ZIF (100 MHz steps) now only shown in GUI when developer menu is enabled
- GUI PLL Reference control now works in Sweep mode
- Darkened trace color in GUI for attenuated edges and dc offset now matches trace color
- Alternate sweep step color in GUI now matches trace color
- DC offset region now limited to middle three bins in GUI (was expanding when decimation was applied)
- Correction to usable region in ZIF and SH modes with decimation applied
- Fixed HDR center offset value
- Added device information dialog to GUI
PyRF 2.6.0¶
2014-09-30
- Added channel power measurement feature to GUI
- Added Export to CSV feature to GUI for saving streams of processed power spectrum data
- Added a power level cursor (adjustable horizontal line) to GUI
- Added reference level offset adjustment box to GUI
- Trigger region in GUI is now a rectangle to make it visibly different than channel power measurement controls
- Update mode drop-down in GUI to include information about each mode instead of showing internal mode names
- Use netifaces for address detection to fix discover issue on non-English windows machines
PyRF 2.5.0¶
2014-09-09
- Added Persistence plot
- Made markers drag-able in the plot
- Added version number to title bar
- Moved DSP options to developer menu, developer menu now hidden unless GUI run with -d option
- Rounded center to nearest tuning resolution step in GUI
- Fixed a number of GUI control and label issues
- Moved changelog into docs and updated
PyRF 2.3.0¶
2014-08-12
- Added full playback support (including sweep) in GUI
- Added hdr_gain control to WSA class
- Added average mode and clear button for traces
- Added handling for different REFLEVEL_ERROR on early firmware versions
- Disable triggers for unsupported WSA firmware versions
- Added free plot adjustment developer option
- Fixed a number of GUI interface issues
PyRF 2.2.0¶
2014-07-15
- Added waterfall display for GUI and example program
- Added automatic re-tuning when plot dragged of zoomed
- Added recording speca state in recorded VRT files, Start/Stop recording menu
- Added GUI non-sweep playback support and command line ‘-p’ option
- Added marker controls: peak left, right, center to marker
- Redesigned frequency controls, device controls and trace controls
- Default to Sweep SH mode in GUI
- Added developer options menu for attenuated edges etc.
- Refactored shared GUI code and panels
- SweepDevice now returns numpy arrays of dBm values
- Fixed device discovery with multiple interfaces
- Replaced reflevel adjustment properties with REFLEVEL_ERROR value
- Renamed GUI launcher to rtsa-gui
PyRF 2.1.0¶
2014-06-20
- Refactored GUI code to separate out device control and state
- Added SPECA defaults to device properties
- Restored trigger controls in GUI
- Added DSP panel to control fft calculations in GUI
- Fixed a number of GUI plot issues
PyRF 2.0.3¶
2014-06-03
- Added simple QT GUI example with frequency, attenuation and rbw controls
- Added support for more hardware versions
- Fixed plotting issues in a number of modes in GUI
PyRF 2.0.1¶
2014-04-21
- Added Sweep SH mode support to SweepDevice
- Added IQ in, DD, SHN RFE modes to GUI
- Added IQ output path and PLL reference controls to GUI
- Added discovery widget to GUI for finding devices
- Fixed a number of issues
PyRF 2.0.0¶
- 2014-01-31
- Added multiple traces and trace controls to GUI
- Added constellation and IQ plots
- Added raw VRT capture-to-file support
- Updated SweepDevice sweep plan calculation
- Created separate GUI for single capture modes
- Updated device properties for WSA5000 RFE modes
- Show attenuated edges in gray, sweep steps in different colors in GUI
- Added decimation and frequency shift controls to single capture GUI
- Fixed many issues with WSA5000 different RFE mode support
- Removed trigger controls, waiting for hardware support
- Switched to using pyinstaller for better windows build support
PyRF 1.2.0¶
- 2013-10-01
- Added WSA5000 support
- Added WSA discovery example scripts
- Renamed WSA4000 class to WSA (supports WSA5000 as well)
- Separated device properties from WSA class
PyRF 1.1.0¶
- 2013-07-19
- Fixed some py2exe issues
- Show the GUI even when not connected
PyRF 1.0.0¶
2013-07-18
- Switched to pyqtgraph for spectrum plot
- Added trigger controls
- Added markers
- Added hotkeys for control
- Added bandwidth control
- Renamed GUI launcher speca-gui
- Created SweepDevice to generalize spectrum analyzer-type function
- Created CaptureDevice to collect single captures and related context
PyRF 0.4.0¶
2013-05-18
pyrf.connectors.twisted_async.TwistedConnector now has a vrt_callback attribute for setting a function to call when VRT packets are received.
This new callback takes a single parameter: a pyrf.vrt.DataPacket or pyrf.vrt.ContextPacket instance.
The old method of emulating a synchronous read() interface from a pyrf.devices.thinkrf.WSA4000 instance is no longer supported, and will now raise a pyrf.connectors.twisted_async.TwistedConnectorError exception.
New methods added to pyrf.devices.thinkrf.WSA4000: abort(), spp(), ppb(), stream_start(), stream_stop(), stream_status()
Added support for stream ID context packets and provide a value for sweep ID context packet not converted to a hex string
wsa4000gui updated to use vrt callback
“wsa4000gui -v” enables verbose mode which currently shows SCPI commands sent and responses received on stdout
Added examples/stream.py example for testing stream data rate
Updated examples/twisted_show_i_q.py for new vrt_callback
Removed pyrf.twisted_util module which implemented old synchronous read() interface
Removed now unused pyrf.connectors.twisted_async.VRTTooMuchData exception
Removed wsa4000gui-blocking script
Fix for power spectrum calculation in pyrf.numpy_util
PyRF 0.3.0¶
2013-02-01
- API now allows asynchronous use with TwistedConnector
- GUI now uses asynchronous mode, but synchronous version may still be built as wsa4000gui-blocking
- GUI moved from examples to inside the package at pyrf.gui and built from the same setup.py
- add Twisted version of show_i_q.py example
- documentation: installation instructions, requirements, py2exe instructions, user manual and many other changes
- fix support for reading WSA4000 very low frequency range
- pyrf.util.read_data_and_reflevel() was renamed to read_data_and_context()
- pyrf.util.socketread() was moved to pyrf.connectors.blocking.socketread()
- added requirements.txt for building dependencies from source
python-thinkrf 0.2.0¶
2012-12-09
- GUI: add BPF toggle, Antenna switching, –reset option, “Open Device” dialog, IF Gain control, Span control, RBW control, update freq on finished editing
- create basic documentation and reference and improve docstrings
- bug fixes for GUI, py2exe setup.py
- GUI perfomance improvements
Hardware Support¶
This library currently supports development for the following ThinkRF Real-Time Spectrum Analyzer (RTSA) platforms:
- R5500
- R5700
- WSA5000 (EOL)