Reference¶

pyrf.devices¶

.thinkrf¶

pyrf.sweep_device¶

class pyrf.sweep_device.SweepDevice(real_device, async_callback=None)¶

Virtual device that generates power levels from a range of frequencies by sweeping the frequencies with a real device and piecing together FFT results.

Parameters:	real_device – device that will will be used for capturing data, typically a `pyrf.devices.thinkrf.WSA` instance. callback – callback to use for async operation (not used if real_device is using a `PlainSocketConnector`)

capture_power_spectrum(fstart, fstop, rbw, device_settings=None, mode='ZIF', continuous=False, min_points=32)¶

Initiate a capture of power spectral density by setting up a sweep list and starting a single sweep.

Parameters:

fstart (float) – starting frequency in Hz
fstop (float) – ending frequency in Hz
rbw (float) – requested RBW in Hz (output RBW may be smaller than requested)
device_settings – antenna, gain and other device settings
mode (string) – sweep mode, ‘ZIF left band’, ‘ZIF’ or ‘SH’
continuous (bool) – async continue after first sweep
min_points (int) – smallest number of points per capture from real_device

exception pyrf.sweep_device.SweepDeviceError¶

class pyrf.sweep_device.SweepStep¶

Data structure used by SweepDevice for planning sweeps

Parameters:

fcenter – starting center frequency in Hz
fstep – frequency increment each step in Hz
fshift – frequency shift in Hz
decimation – decimation value
points – samples to capture
bins_skip – number of FFT bins to skip from left
bins_run – number of usable FFT bins each step
bins_pass – number of bins from first step to discard from left
bins_keep – total number of bins to keep from all steps

steps¶

to_sweep_entry(device, rfe_mode, **kwargs)¶

Create a SweepEntry for device matching this SweepStep,

extra parameters (gain, antenna etc.) may be provided as keyword parameters

pyrf.sweep_device.plan_sweep(device, fstart, fstop, rbw, mode, min_points=32)¶

Parameters:

device – a device class or instance such as pyrf.devices.thinkrf.WSA
fstart (float) – starting frequency in Hz
fstop (float) – ending frequency in Hz
rbw (float) – requested RBW in Hz (output RBW may be smaller than requested)
mode (string) – sweep mode, ‘ZIF left band’, ‘ZIF’ or ‘SH’
min_points (int) – smallest number of points per capture

The following device properties are used in planning the sweep:

device.properties.FULL_BW: full width of the filter in Hz
device.properties.USABLE_BW: usable portion before filter drop-off at edges in Hz
device.properties.MIN_TUNABLE: the lowest valid center frequency for arbitrary tuning in Hz, 0(DC) is always assumed to be available for direct digitization
device.properties.MAX_TUNABLE: the highest valid center frequency for arbitrart tuning in Hz
device.properties.DC_OFFSET_BW: the range of frequencies around center that may be affected by a DC offset and should not be used
device.properties.TUNING_RESOLUTION: the smallest tuning increment for fcenter and fstep

Returns:	(actual fstart, actual fstop, list of SweepStep instances)

The caller would then use each of these tuples to do the following:

The first 5 values are used for a single capture or single sweep
An FFT is run on the points returned to produce bins in the linear domain
bins[bins_skip:bins_skip + bins_run] are selected
take logarithm of output bins and appended to the result
for sweeps repeat from 2 until the sweep is complete
bins_pass is the number of selected bins to skip from the first capture only
bins_keep is the total number of selected bins to keep; for single captures bins_run == bins_keep

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 – device that will 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 `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=128, force_change=False)¶

Initiate a capture of raw time domain IQ or I-only data

Parameters:	rfe_mode – radio front end mode, e.g. ‘ZIF’, ‘SH’, ... freq – center frequency rbw (float) – requested RBW in Hz (output RBW may be smaller than requested) device_settings – attenuator, decimation frequency shift and other device settings min_points (int) – smallest number of points per capture from real_device

configure_device(device_settings, force_change=False)¶

Configure the device settings on the next capture

Parameters:	device_settings – attenuator, decimation frequency shift and other device settings

read_data(packet)¶

exception pyrf.capture_device.CaptureDeviceError¶

pyrf.connectors¶

.blocking¶

class pyrf.connectors.blocking.PlainSocketConnector¶

This connector makes SCPI/VRT socket connections using plain sockets.

connect(host)¶

disconnect()¶

eof()¶

has_data()¶

raw_read(num)¶

scpiget(cmd)¶

scpiset(cmd)¶

sync_async(gen)¶: Handler for the @sync_async decorator. We convert the generator to a single return value for simple synchronous use.

pyrf.connectors.blocking.socketread(socket, count, flags=None)¶: Retry socket read until count data received, like reading from a file.

.twisted_async¶

class pyrf.connectors.twisted_async.SCPIClient¶

connectionMade()¶

dataReceived(data)¶

scpiget(cmd)¶

scpiset(cmd)¶

class pyrf.connectors.twisted_async.SCPIClientFactory¶

buildProtocol(addr)¶

clientConnectionFailed(connector, reason)¶

clientConnectionLost(connector, reason)¶

startedConnecting(connector)¶

class pyrf.connectors.twisted_async.TwistedConnector(reactor, vrt_callback=None)¶

A connector that makes SCPI/VRT connections asynchronously using Twisted.

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.

connect(host, output_file=None)¶

disconnect()¶

eof()¶

inject_recording_state(state)¶

raw_read(num_bytes)¶

scpiget(cmd)¶

scpiset(cmd)¶

set_recording_output(output_file=None)¶

sync_async(gen)¶

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

connectionLost(reason)¶

dataReceived(data)¶

eof = False¶

inject_recording_state(state)¶

makeConnection(transport)¶

set_recording_output(output_file=None)¶

class pyrf.connectors.twisted_async.VRTClientFactory(receive_callback)¶

buildProtocol(addr)¶

clientConnectionFailed(connector, reason)¶

clientConnectionLost(connector, reason)¶

startedConnecting(connector)¶

pyrf.config¶

class pyrf.config.SweepEntry(fstart=2400000000, fstop=2400000000, fstep=100000000, fshift=0, decimation=0, antenna=1, 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=True, rfe_mode='ZIF')¶

Sweep entry for pyrf.devices.thinkrf.WSA.sweep_add()

Parameters:

fstart – starting frequency in Hz
fstop – ending frequency in Hz
fstep – frequency step in Hz
fshift – the frequency shift in Hz
decimation – the decimation value (0 or 4 - 1023)
antenna – the antenna (1 or 2)
gain – the RF gain value (‘high’, ‘medium’, ‘low’ or ‘vlow’)
ifgain – the IF gain in dB (-10 - 34)
hdr_gain – the HDR gain in dB (-10 - 30)
spp – samples per packet
ppb – packets per block
dwell_s – dwell time seconds
dwell_us – dwell time microseconds
trigtype – trigger type (‘none’, ‘pulse’ or ‘level’)
level_fstart – level trigger starting frequency in Hz
level_fstop – level trigger ending frequency in Hz
level_amplitude – level trigger minimum in dBm
attenuator – enable/disable attenuator
rfe_mode – RFE mode to be used

class pyrf.config.TriggerSettings(trigtype='NONE', fstart=None, fstop=None, amplitude=None)¶

Trigger settings for pyrf.devices.thinkrf.WSA.trigger().

Parameters:	trigtype – “LEVEL” or “NONE” to disable fstart – starting frequency in Hz fstop – ending frequency in Hz amplitude – minumum level for trigger in dBm

exception pyrf.config.TriggerSettingsError¶

pyrf.numpy_util¶

pyrf.numpy_util.calculate_channel_power(power_spectrum)¶: Return a dBm value representing the channel power of the input power spectrum. :param power_spectrum: array containing power spectrum to be used for

the channel power calculation

pyrf.numpy_util.compute_fft(dut, data_pkt, context, correct_phase=True, hide_differential_dc_offset=True, convert_to_dbm=True, apply_window=True, apply_spec_inv=True, apply_reference=True, ref=None)¶

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 containing context values correct_phase – apply phase correction for captures with IQ data hide_differential_dc_offset – mask the differential DC offset present in captures with IQ data convert_to_dbm – convert the output values to dBm
Returns:	numpy array of dBm values as floats

pyrf.util¶

pyrf.util.read_data_and_context(dut, points=1024)¶

Initiate capture of one data packet, wait for and return data packet and collect preceeding context packets.

Returns:	(data_pkt, context_values)

Where context_values is a dict of {field_name: value} items from all the context packets received.

pyrf.util.collect_data_and_context(dut)¶: Wait for and return data packet and collect preceeding context packets.

pyrf.vrt¶

class pyrf.vrt.ContextPacket(packet_type, count, size, tmpstr, has_timestamp)¶

A Context Packet received from pyrf.devices.thinkrf.WSA.read()

fields¶: a dict containing field names and values from the packet

is_context_packet(ptype=None)¶

Parameters:	ptype – “Receiver”, “Digitizer” or None for any

packet type

Returns:	True if this packet matches the type passed

is_data_packet()¶

Returns:	False

class pyrf.vrt.DataArray(binary_data, bytes_per_sample)¶

Data Packet values as a lazy array read from binary_data.

Parameters:	bytes_per_sample – 1 for PSD8 data, 2 for I14 data or 4 for I24 data

numpy_array()¶: return a numpy array for this data

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 similar to:

exception pyrf.vrt.InvalidDataReceived¶

pyrf.vrt.generate_speca_packet(data, count=0)¶

Parameters:	data – a python dict that can be serialized as JSON count – int count for the header of this packet
Returns:	(vrt packet bytes, next count int)

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.