Reference¶
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)¶
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.