Reference¶
pyrf.devices¶
.thinkrf¶
-
class
pyrf.devices.thinkrf.
WSA
(connector=None)¶ Interface for WSA4000 and WSA5000
Parameters: connector – Connector object to use for SCPI/VRT connections, defaults to a new PlainSocketConnector
instanceconnect()
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.-
abort
()¶ This command will cause the WSA to stop the data capturing, whether in the manual trace block capture, triggering or sweeping mode. The WSA 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.
-
antenna
(number=None)¶ This command selects and queries the active antenna port.
Parameters: number – 1 or 2 to set; None to query Returns: active antenna port
-
apply_device_settings
(settings)¶ This command takes a dict of device settings, and applies them to the WSA Note this method only applies a setting if it has been changed using this method :param settings: dict containing settings such as attenuation,decimation,etc
-
attenuator
(enable=None)¶ This command enables, disables or queries the WSA’s RFE 20 dB attenuation.
Parameters: enable – True or False to set; None to query Returns: the current attenuator state
-
capture
(spp, ppb)¶ This command will start the single block capture and the return of ppb packets of spp samples each. 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.
Parameters: - spp – the number of samples in a packet
- ppb – the number of packets in a capture
-
connect
(host)¶ connect to a wsa
Parameters: host – the hostname or IP to connect to
-
decimation
(value=None)¶ This command sets or queries the rate of decimation of samples in a trace capture. This decimation method consists of cascaded integrator-comb (CIC) filters and at every value number of samples, one sample is captured. The supported rate is 4 - 1023. When the rate is set to 1, no decimation is performed on the trace capture.
Parameters: value (int) – new decimation value (1 or 4 - 1023); None to query Returns: the decimation value
-
disconnect
()¶ close a connection to a wsa
-
eof
()¶ Check if the VRT stream has closed.
Returns: True if no more data, False if more data
-
errors
()¶ Flush and return the list of errors from past commands sent to the WSA. An empty list is returned when no errors are present.
-
flush
()¶ This command clears the WSA’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 packet.
-
flush_captures
()¶ Flush capture memory of sweep captures.
-
freq
(freq=None)¶ This command sets or queries the tuned center frequency of the WSA.
Parameters: freq (int) – the new center frequency in Hz (0 - 10 GHz); None to query Returns: the frequency in Hz
-
fshift
(shift=None)¶ This command sets or queries the frequency shift value.
Parameters: freq (int) – the new frequency shift in Hz (0 - 125 MHz); None to query Returns: the amount of frequency shift
-
gain
(gain=None)¶ This command sets or queries RFE quantized gain configuration. The RF front end (RFE) of the WSA consists of multiple quantized gain stages. The gain corresponding to each user-selectable setting has been pre-calculated for either optimal sensitivity or linearity. The parameter defines the total quantized gain of the RFE.
Parameters: gain – ‘high’, ‘medium’, ‘low’ or ‘vlow’ to set; None to query Returns: the RF gain value
-
has_data
()¶ Check if there is VRT data to read.
Returns: True if there is a packet to read, False if not
-
have_read_perm
()¶ Check if we have permission to read data.
Returns: True if allowed to read, False if not
-
id
()¶ Returns the WSA’s identification information string.
Returns: “<Manufacturer>,<Model>,<Serial number>,<Firmware version>”
-
ifgain
(gain=None)¶ This command sets or queries variable IF gain stages of the RFE. The gain has a range of -10 to 34 dB. This stage of the gain is additive with the primary gain stages of the LNA that are described in
gain()
.Parameters: gain – float between -10 and 34 to set; None to query Returns: the ifgain in dB
-
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 digital card.
Parameters: modulestr – ‘vco’ for rf lock status, ‘clkref’ for mobo lock status Returns: True if locked
-
ppb
(packets=None)¶ This command sets the number of IQ packets in a capture block
Parameters: packets – the number of samples in a packet Returns: the current ppb value if the packets parameter is None
-
preselect_filter
(enable=None)¶ This command sets or queries the RFE preselect filter selection.
Parameters: enable – True or False to set; None to query Returns: the RFE preselect filter selection state
-
raw_read
(num)¶ Raw read of VRT socket data from the WSA.
Parameters: num – the number of bytes to read Returns: bytes
-
read
()¶ Read a single VRT packet from the WSA.
-
request_read_perm
()¶ Acquire exclusive permission to read data from the WSA.
Returns: True if allowed to read, False if not
-
reset
()¶ Resets the WSA to its default settings. It does not affect the registers or queues associated with the IEEE mandated commands.
-
scpiget
(cmd)¶ Send a SCPI command and wait for the response.
This is the lowest-level interface provided. Please see the Programmer’s Guide for information about the commands available.
Parameters: cmd (str) – the command to send Returns: the response back from the box if any
-
scpiset
(cmd)¶ Send a SCPI command.
This is the lowest-level interface provided. Please see the Programmer’s Guide for information about the commands available.
Parameters: cmd (str) – the command to send
-
spp
(samples=None)¶ This command sets or queries the number of Samples Per Packet (SPPacket).
The upper bound of the samples is limited by the VRT’s 16-bit packet size field less the VRT header and any optional fields (i.e. Stream ID, Class ID, Timestamps, and trailer) of 32-bit wide words. However since the SPP must be a multiple of 16, the maximum is thus limited by 2**16 - 16.
Parameters: samples – the number of samples in a packet or None Returns: the current spp value if the samples parameter is None
-
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 WSA whenever data is available.
Parameters: stream_id – optional unsigned 32-bit stream identifier
-
stream_status
()¶ This query returns the current running status of the stream capture mode.
Returns: ‘RUNNING’ or ‘STOPPED’
-
stream_stop
()¶ This command stops the stream capture. After receiving the command, the WSA system will stop when the current capturing VRT packet is completed.
-
sweep_add
(entry)¶ Add an entry to the sweep list
Parameters: entry (pyrf.config.SweepEntry) – the sweep entry to add
-
sweep_clear
()¶ Remove all entries from the sweep list.
-
sweep_read
(index)¶ Read an entry from the sweep list.
Parameters: index – the index of the entry to read Returns: sweep entry Return type: pyrf.config.SweepEntry
-
sweep_start
(start_id=None)¶ Start the sweep engine.
-
sweep_stop
()¶ Stop the sweep engine.
-
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
-
-
pyrf.devices.thinkrf.
parse_discovery_response
(response)¶ This function parses the WSA’s raw discovery response
Parameters: response – The WSA’s raw response to a discovery query Returns: Return (model, serial, firmware version) based on a discovery response message
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
- real_device – device that will will be used for capturing data,
typically a
-
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
- device – a device class or instance such as
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)¶
- real_device – device that will will be used for capturing data,
typically a
-
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.