PrawnBlaster

This labscript device controls the PrawnBlaster open-source digital pattern generator based on the Raspberry Pi Pico platform.

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)

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: labscript.labscript.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'>]
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'
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: labscript.labscript.ClockLine

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

add_device(device)[source]
generate_code(*args, **kwargs)[source]
class labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterDummyIntermediateDevice(name, parent_device, **kwargs)[source]

Bases: labscript.labscript.IntermediateDevice

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

add_device(device)[source]
generate_code(*args, **kwargs)[source]
class labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterDummyPseudoclock(name, pseudoclock_device, connection, **kwargs)[source]

Bases: labscript.labscript.Pseudoclock

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

add_device(device)[source]
generate_code(*args, **kwargs)[source]
class labscript_devices.PrawnBlaster.labscript_devices._PrawnBlasterPseudoclock(i, *args, **kwargs)[source]

Bases: labscript.labscript.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: blacs.device_base_class.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: blacs.tab_base_classes.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)

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