PrawnBlaster

This labscript device controls the PrawnBlaster open-source digital pattern generator based on the Raspberry Pi Pico platform. It is designed to produce pseudoclock timing pulses. See the companion PrawnDO device for arbitary pulse generation.

Specifications

The PrawnBlaster takes advantage of the specs of the Pico to provide the following:

Configurable as 1, 2, 3, or 4 truly independent pseudoclocks.
- Each clock has its own independent instruction set and synchronization between clocks is not required.
- Assuming the default internal clock of 100 MHz, each clock has:
  - Minimum pulse half-period of 50 ns
  - Maximum pulse half-period of 42.9 s
  - Half-period resolution of 10 ns
30,000 instructions (each with up to 2^32 repetitions) distributed evenly among the configured pseudoclocks; 30,000, 15,000, 10,000, and 7,500 for 1, 2, 3, 4 pseudoclocks respectively.
Support for external hardware triggers (external trigger common to all pseudoclocks)
- Up to 100 retriggers (labscript-suite waits) per pseudoclock
- Each wait can support a timeout of up to 42.9 s
- Each wait is internally monitored for its duration (resolution of +/-10 ns)
Can be referenced to an external LVCMOS clock
Internal clock can be set up to 133 MHz (timing specs scale accordingly)

Installation

In order to turn the standard Pico into a PrawnBlaster, you need to load the custom firmware available in the Github repo onto the board. The simplest way to do this is by holding the reset button on the board while plugging the USB into a computer. This will bring up a mounted folder that you copy-paste the firmware to. Once copied, the board will reset and be ready to go.

Note that this device communicates using a virtual COM port. The number is assigned by the controlling computer and will need to be determined in order for BLACS to connect to the PrawnBlaster.

Usage

The default pinout for the PrawnBlaster is as follows:

Pseudoclock 0 output: GPIO 9
Pseudoclock 1 output: GPIO 11
Pseudoclock 2 output: GPIO 13
Pseudoclock 3 output: GPIO 15
External Triggeer input: GPIO 0
External Clock input: GPIO 20

Note that signal cable grounds should be connected to the digital grounds of the Pico for proper operation.

The PrawnBlaster provides up to four independent clocklines. They can be accessed either by name.clocklines[int] or directly by their auto-generated labscript names name_clock_line_int.

An example connection table that uses the PrawnBlaster:

from labscript import *

from labscript_devices.PrawnBlaster.labscript_devices import PrawnBlaster
from labscript_devices.NI_DAQmx.models.NI_USB_6363 import NI_USB_6363

PrawnBlaster(name='prawn', com_port='COM6', num_pseudoclocks=1)

NI_USB_6363(name='daq', MAX_name='Dev1',
            parent_device=prawn.clocklines[0], clock_terminal='/Dev1/PFI0',
            acquisition_rate=100e3)

AnalogOut('ao0', daq, 'ao0')
AnalogOut('ao1', daq, 'ao1')

if __name__ == '__main__':

   start(0)

   stop(1)

Input/Output Buffers

While the PrawnBlaster and PrawnDO boards can be used as is, it is often a good idea to add unity-gain channel buffers to the inputs and outputs. Using buffers and line drivers from a LVCMOS family with 5V/TTL tolerant inputs can provide compatibility with TTL inputs and drive higher capacitance loads (such a long BNC cables) more reliably. Examples that implement these buffers can be found here and here.

Detailed Documentation

class labscript_devices.PrawnBlaster.labscript_devices.PrawnBlaster(name, trigger_device=None, trigger_connection=None, com_port='COM1', num_pseudoclocks=1, out_pins=None, in_pins=None, clock_frequency=100000000.0, external_clock_pin=None, use_wait_monitor=True)[source]

Bases: PseudoclockDevice

PrawnBlaster Pseudoclock labscript device.

This labscript device creates Pseudoclocks based on the PrawnBlaster, a Raspberry Pi Pico with custom firmware.

Parameters:

name (str) – python variable name to assign to the PrawnBlaster
com_port (str) – COM port assigned to the PrawnBlaster by the OS. Takes the form of 'COMd', where d is an integer.
num_pseudoclocks (int) – Number of pseudoclocks to create. Ranges from 1-4.
trigger_device (IntermediateDevice, optional) – Device that will send the hardware start trigger when using the PrawnBlaster as a secondary Pseudoclock.
trigger_connection (str, optional) – Which output of the trigger_device is connected to the PrawnBlaster hardware trigger input.
out_pins (list, optional) – What outpins to use for the pseudoclock outputs. Must have length of at least num_pseudoclocks. Defaults to [9,11,13,15]
in_pins (list, optional) – What inpins to use for the pseudoclock hardware triggering. Must have length of at least num_pseudoclocks. Defaults to [0,0,0,0]
clock_frequency (float, optional) – Frequency of clock. Standard range accepts up to 133 MHz. An experimental overclocked firmware is available that allows higher frequencies.
external_clock_pin (int, optional) – If not None (the default), the PrawnBlaster uses an external clock on the provided pin. Valid options are 20 and 22. The external frequency must be defined using clock_frequency.
use_wait_monitor (bool, optional) – Configure the PrawnBlaster to perform its own wait monitoring.

add_device(device)[source]

Adds child devices.

This is automatically called by the labscript compiler.

Parameters:: device (_PrawnBlasterPseudoclock or _PrawnBlasterDummyPseudoclock) – Instance to attach to the device. Only the allowed children can be attached.

allowed_children = [<class 'labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterPseudoclock'>, <class 'labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterDummyPseudoclock'>]

Defines types of devices that are allowed to be children of this device.

Type:: list

clock_limit = 10000000.0: Maximum allowable clock rate.

clock_resolution = 2e-08: Minimum resolvable time for a clock tick.

property clocklines: Returns a list of the automatically generated ClockLine objects.

description = 'PrawnBlaster': Brief description of the device.

generate_code(hdf5_file)[source]

Generates the hardware instructions for the pseudoclocks.

This is automatically called by the labscript compiler.

Parameters:: hdf5_file (h5py.File) – h5py file object for shot

input_response_time = 5e-08: Time necessary for hardware to respond to a hardware trigger. Empirically determined to be a ~50 ns buffer on the input.

property internal_wait_monitor_outputs

max_instructions = 30000: Maximum numaber of instructions per pseudoclock. Max is 30,000 for a single pseudoclock.

property pseudoclocks: Returns a list of the automatically generated _PrawnBlasterPseudoclock objects.

trigger_delay = 1.3e-07: Processing time delay after trigger is detected. Due to firmware, there is an 80 ns delay between trigger detection and first output pulse.

trigger_minimum_duration = 1.6e-07: Minimum required width of hardware trigger. An overestimate that covers currently unsupported indefinite waits.

wait_delay = 4e-08: Minimum required length of a wait before retrigger can be detected. Corresponds to 4 instructions.

class labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterDummyClockLine(name, pseudoclock, connection, ramping_allowed=True, **kwargs)[source]

Bases: ClockLine

Dummy Clockline labscript device used internally to allow WaitMonitor to work internally to the PrawnBlaster.

Creates a Device.

Parameters:

name (str) – python variable name to assign this device to.
parent_device (Device) – Parent of this device.
connection (str) – Connection on this device that links to parent.
call_parents_add_device (bool, optional) – Flag to command device to call its parent device’s add_device when adding a device.
added_properties (dict, optional) –
gui –
worker –
start_order (int, optional) – Priority when starting, sorted with all devices.
stop_order (int, optional) – Priority when stopping, sorted with all devices.
**kwargs – Other options to pass to parent.

add_device(device)[source]

Adds a child device to this device.

Parameters:: device (Device) – Device to add.
Raises:: LabscriptError – If device is not an allowed child of this device.

generate_code(*args, **kwargs)[source]

Generate hardware instructions for device and children, then save to h5 file.

Will recursively call generate_code for all children devices.

Parameters:: hdf5_file (h5py.File) – Handle to shot file.

class labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterDummyIntermediateDevice(name, parent_device, **kwargs)[source]

Bases: IntermediateDevice

Dummy intermediate labscript device used internally to attach WaitMonitor objects to the PrawnBlaster.

Provides some error checking to ensure parent_device is a ClockLine.

Calls Device.__init__().

Parameters:

name (str) – python variable name to assign to device
parent_device (ClockLine) – Parent ClockLine device.

add_device(device)[source]

Adds a child device to this device.

Parameters:: device (Device) – Device to add.
Raises:: LabscriptError – If device is not an allowed child of this device.

generate_code(*args, **kwargs)[source]

Generate hardware instructions for device and children, then save to h5 file.

Will recursively call generate_code for all children devices.

Parameters:: hdf5_file (h5py.File) – Handle to shot file.

class labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterDummyPseudoclock(name, pseudoclock_device, connection, **kwargs)[source]

Bases: Pseudoclock

Dummy Pseudoclock labscript device used internally to allow WaitMonitor to work internally to the PrawnBlaster.

Creates a Pseudoclock.

Parameters:

name (str) – python variable name to assign the device instance to.
pseudoclock_device (PseudoclockDevice) – Parent pseudoclock device
connection (str) – Connection on this device that links to parent
**kwargs – Passed to Device().

add_device(device)[source]

Adds a child device to this device.

Parameters:: device (Device) – Device to add.
Raises:: LabscriptError – If device is not an allowed child of this device.

generate_code(*args, **kwargs)[source]

Generate hardware instructions for device and children, then save to h5 file.

Will recursively call generate_code for all children devices.

Parameters:: hdf5_file (h5py.File) – Handle to shot file.

class labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterPseudoclock(i, *args, **kwargs)[source]

Bases: Pseudoclock

Customized Clockline for use with the PrawnBlaster.

This Pseudoclock retains information about which hardware clock it is associated with, and ensures only one clockline per pseudoclock.

Parameters:: i (int) – Specifies which hardware pseudoclock this device is associated with.

add_device(device)[source]

Parameters:: device (ClockLine) – Clockline to attach to the pseudoclock.

class labscript_devices.PrawnBlaster.blacs_tabs.PrawnBlasterTab(notebook, settings, restart=False)[source]

Bases: DeviceTab

BLACS Tab for the PrawnBlaster Device.

get_child_from_connection_table(parent_device_name, port)[source]

Finds the attached ClockLines.

Parameters:

parent_device_name (str) – name of parent_device
port (str) – port of parent_device

Returns:

PrawnBlaster interal Clocklines

Return type:

ClockLine

initialise_GUI()[source]

Initialises the Tab GUI.

This method is called automatically by BLACS.

initialise_workers()[source]

Initialises the PrawnBlaster Workers.

This method is called automatically by BLACS.

start_run(*args, **kwargs)

status_monitor(*args, **kwargs)

class labscript_devices.PrawnBlaster.blacs_workers.PrawnBlasterWorker(*args, **kwargs)[source]

Bases: Worker

The primary worker for the PrawnBlaster.

This worker handles configuration and communication with the hardware.

abort_buffered()[source]

Aborts a currently running buffered execution.

Returns:: True is abort is successful.
Return type:: bool

abort_transition_to_buffered()[source]

Aborts a transition to buffered.

Calls abort_buffered().

check_status()[source]

Checks the operational status of the PrawnBlaster.

This is automatically called by BLACS to update the status of the PrawnBlaster. It also reads the lengths of any accumulated waits during a shot.

Returns:

Tuple containing:

run_status (int): Possible values are:
- 0 : manual-mode
- 1 : transitioning to buffered execution
- 2 : buffered execution
- 3 : abort requested
- 4 : currently aborting buffered execution
- 5 : last buffered execution aborted
- 6 : transitioning to manual mode
clock_status (int): Possible values are:
- 0 : internal clock
- 1 : external clock
waits_pending (bool): Indicates if all expected waits have not been read out yet.

Return type:

(int, int, bool)

get_version()[source]

init()[source]

Initialises the hardware communication.

This function is automatically called by BLACS and configures hardware communication with the device.

program_manual(values)[source]

Manually sets the state of output pins for the pseudoclocks.

Parameters:: values (dict) – Dictionary of pseudoclock: value pairs to set.
Returns:: values from arguments on successful programming reflecting current output state.
Return type:: dict

read_status()[source]

Reads the status of the PrawnBlaster.

Returns:

Tuple containing

run-status (int): Run status code

clock-status (int): Clock status code

Return type:

(int, int)

shutdown()[source]: Cleanly shuts down the connection to the PrawnBlaster hardware.

start_run()[source]: When used as the primary pseudoclock, starts execution in software time to engage the shot.

transition_to_buffered(device_name, h5file, initial_values, fresh)[source]

Configures the PrawnBlaster for buffered execution.

Parameters:

device_name (str) – labscript name of PrawnBlaster
h5file (str) – path to shot file to be run
initial_values (dict) – Dictionary of output states at start of shot
fresh (bool) – When True, clear the local smart_cache, forcing a complete reprogramming of the output table.

Returns:

Dictionary of the expected final output states.

Return type:

dict

transition_to_manual()[source]

Transition the PrawnBlaster back to manual mode from buffered execution at the end of a shot.

Returns:: True if transition to manual is successful.
Return type:: bool

wait_for_trigger()[source]: When used as a secondary pseudoclock, sets the PrawnBlaster to wait for an initial hardware trigger to begin execution.

class labscript_devices.PrawnBlaster.runviewer_parsers.PrawnBlasterParser(path, device)[source]

Bases: object

Runviewer parser for the PrawnBlaster Pseudoclocks.

Parameters:

path (str) – path to h5 shot file
device (str) – labscript name of PrawnBlaster device

get_traces(add_trace, clock=None)[source]

Reads the shot file and extracts hardware instructions to produce runviewer traces.

Parameters:

add_trace (func) – function handle that adds traces to runviewer
clock (tuple, optional) – clock times from timing device, if not the primary pseudoclock

Returns:

Dictionary of clocklines and triggers derived from instructions

Return type:

dict