API

This is where the documentation for the public API functions, and classes lives.

PhyWhisperer-USB Main Interface

class Usb(viewsb=False)

PhyWhisperer-USB Interface

arm()

Arm PhyWhisperer for capture and optionally generating a trigger. Use set_pattern to program the pattern and bitmask which will initiate the capture and/or trigger operation. Use set_trigger to program the trigger parameters. Use set_capture_size and set_capture_delay to program the capture parameters.

armed()

Returns True if the PhyWhisperer is armed.

check_fifo_errors(underflow=0, overflow_blocked=0)

Check whether an underflow or overflow occured on the capture FIFO. (Overflows are blocked, underflows are not.)

Parameters:
  • underflow (int, optional) – expected status, 0 or 1
  • overflow_blocked (int, optional) – expected status, 0 or 1
close()

Terminates our connection to the PhyWhisperer device.

con(PID=50704, sn=None, program_fpga=True)

Connect to PhyWhisperer-USB. Raises error if multiple detected

Parameters:
  • PID (int, optional) – USB PID of PhyWhisperer, defaults to 0xC610 (NewAE standard).
  • sn (int, option) – Serial Number of PhyWhisperer, required when multiple PhyWhisperers are connected.
  • program_fpga (bool, option) – Specifies whether or not to program the FPGA with the default firmware when we connect. Set to False if using custom bitstream.
erase_sam3u()

Erase the SAM3U Firmware, which forces it into bootloader mode.

fifo_empty()

Returns True if the capture FIFO is empty, False otherwise.

fifo_over_empty_threshold()

Returns True if the capture FIFO has more entries than the empty threshold (128).

get_fpga_buildtime()

Returns date and time when FPGA bitfile was generated.

get_usb_mode()

Returns USB PHY speed. A return value of ‘auto’ means that the speed has not been determined yet (was the mode set to ‘auto’ _before_ the target was connected or powered up?).

load_bitstream(bitfile)

Load bitstream onto FPGA

ms_trigger(delay_in_ms)

Convert a mS number to delay or width cycles for set_trigger()

ns_trigger(delay_in_ns)

Convert a nS number to delay or width cycles for set_trigger()

program_sam3u(port, fw_path=None)

Program the SAM3U Firmware assuming device is in bootloader mode.

Parameters:port (str) – Serial port name, such as ‘COM36’ or ‘/dev/ttyACM0’.
read_capture_data(entries=0, verbose=False, blocking=False, burst_size=8192, timeout=10)

Read from USB capture memory.

Parameters:
  • blocking (bool, optional) –
    • True: wait for data to be available before reading (slower).
    • False: read immediately, with underflow protection, all of the captured data, until PW tells us we’ve read everything (‘entries’ is ignored).
  • entries (int, optional) – When blocking=True, number of capture entries to read. If not specified, read all the captured data. Cannot be greater than capture size, as set by set_capture_size().
  • burst_size (int, optional) – When blocking=False, size of burst FIFO reads, defaults to 8192.
  • timeout (int, optional) – timeout in seconds (ignored if 0, defaults to 10)
  • verbose (bool, optional) – Print extra debug info.

Returns: List of captured entries. Each list element is itself a 3-element list, containing the 3 bytes that make up a capture entry. Can be parsed by split_packets() or split_data().

register_sink(event_sink)

ViewSB: Registers a USBEventSink to receive any USB events.

Parameters:event_sink (sniffer.USBEventSink) – The sniffer.USBEventSink object to receive any USB events that occur.
reset_fpga()

Reset FPGA registers to defaults, use liberally to clear incorrect states.

run_capture(size=8188, burst=True, pattern=[0], mask=[0], statistics_callback=None, statistics_period=0.1, halt_callback=<function Usb.<lambda>>)

Runs a capture for ViewSB, including power cycling the device to catch the descriptors.

Runs following internally:

self.reset_fpga()
self.set_power_source("host")
self.set_power_source("off")
time.sleep(0.5)
self.set_usb_mode("auto")
self.set_capture_size(size)
self.arm()
self.set_trigger(enable=False)
self.set_pattern(pattern=pattern, mask=mask)
self.set_power_source("host")
time.sleep(0.25)
set_capture_delay(delay)

Program the capture delay, measured in clock cycles of USB-derived 60 MHz clock.

Parameters:delay (int) – range in [0, 2^18-1] cycles of 60 MHz clock.
set_capture_size(size=8188)

Set how many events to capture (events include data, USB status, and timestamps).

Parameters:size (int, option) – number of events to capture. 0 = unlimited (until overflow). Max = 2^24-1. Since the capture FIFO can hold 8188 events, setting this to > 8188 may result in overflow.
set_pattern(pattern, mask=None)

Set the pattern and its bitmask used for capture and trigger output.

Parameters:
  • pattern (list of ints) – list of between 1 and 64 bytes
  • mask (list, optional) – list of bytes, must have same size as ‘pattern’ if set. Defaults to [0xff]*len(pattern) if not set.
set_power_source(src)

Set power source for target.

Parameters:src (str) –
  • “5V” for power from this computer (via ‘Control’ USB port).
  • ”host” for power from the host of the connection we’re sniffing.
  • ”off” for no power.
set_stat_pattern(pattern, mask=31)

Set a 5-bit pattern and mask for the USB status lines.

Parameters:
  • pattern (int) – 5-bit number
  • mask (int) – non-zero 5-bit number (default: 0x1f)
set_trigger(delay=0, width=1, enable=True)
Program the output trigger delay and width. Both are measured in clock cycles of USB-derived 240 MHz clock.
The capture delay is automatically set to match the trigger delay; use set_capture_delay to set it to a different value. Use ns_trigger(), us_trigger(), and ms_trigger() to convert values as needed.
Parameters:
  • delay (int) – range in [0, 2^20-1] cycles.
  • width (int) – range in [1, 2^17-1] cycles.
  • enable (bool, optional) – set to ‘False’ to disable trigger generation on hardware pins.
set_usb_mode(mode='auto')

Set USB PHY speed.

Parameters:mode (str) –
  • “LS”: manually set the PHY to low speed.
  • ”FS”: manually set the PHY to full speed.
  • ”HS”: manually set the PHY to high speed.
  • ”auto”: Default. PW will attempt to automatically determine the
    speed when the target is connected. Mode must be set to ‘auto’ prior to connecting the target, otherwise speed cannot be determined correctly. Setting the mode to ‘auto’ actively causes PW to try to determine the speed.
slurp_defines()

Parse Verilog defines file so we can access register and bit definitions by name and avoid ‘magic numbers’.

split_data(rawdata, verbose=False)

Split raw USB capture data into data events and times, stat events and times.

Returns:
  1. data event times
  2. data bytes corresponding to data event times
  3. USB status update times
  4. USB status bytes corresponding to status update times
Return type:4-tuple of lists
split_packets(rawdata)

Split raw USB capture data into packets.

Returns:
list
Each list element is one packet and is presented in a dictionary with the following keys:
  • ’timestamp’
  • ’size’ in bytes
  • ’contents’ list of bytes
stat_pattern_matched()

Returns 1 if a stat pattern match occurred (automatically resets to 0 when armed, and when a new match pattern is written). Actual match value is stored in self.stat_pattern_match_value.

trigger_clock_phase_shift(steps=1)

Shifts the trigger clock phase (and by extension the output trigger) in steps of 18.6ps (18.6 ps = 1/960 MHz / 56)

Parameters:steps (int) – Number of steps to shift the phase (positive or negative integer).
us_trigger(delay_in_us)

Convert a uS number to delay or width cycles for set_trigger()

wait_disarmed()

Blocks until armed() returns false.