msl.equipment.resources.picotech.picoscope.picoscope_api module

Base class for the PicoScopes that have a header file which ends with *Api.h.

Namely, ps2000aApi, ps3000aApi, ps4000Api, ps4000aApi, ps5000Api, ps5000aApi and ps6000Api.

class msl.equipment.resources.picotech.picoscope.picoscope_api.PicoScopeApi(record, func_ptrs)[source]

Bases: PicoScope

Base class for the PicoScopes that have a header file which ends with *Api.h.

Use the PicoScope SDK to communicate with the ps2000a, ps3000a, ps4000, ps4000a, ps5000, ps5000a and ps6000 oscilloscopes.

Do not instantiate this class directly. Use the connect() method to connect to the equipment.

Parameters
errcheck_api(result, func, args)[source]

The SDK function returns PICO_OK if the function call was successful.

change_power_source(power_state)[source]

Change the power source.

This function selects the power supply mode. You must call this function if any of the following conditions arises:

  • USB power is required

  • the AC power adapter is connected or disconnected during use

  • a USB 3.0 scope is plugged into a USB 2.0 port (indicated if any function returns the PICO_USB3_0_DEVICE_NON_USB3_0_PORT status code)

This function is only valid for ps3000a, ps4000a and ps5000a.

current_power_source()[source]

This function returns the current power state of the device.

This function is only valid for ps3000a, ps4000a and ps5000a.

flash_led(action)[source]

This function flashes the LED on the front of the scope without blocking the calling thread. Calls to run_streaming() and run_block() cancel any flashing started by this function. It is not possible to set the LED to be constantly illuminated, as this state is used to indicate that the scope has not been initialized.

get_analogue_offset(voltage_range, coupling)[source]

This function is used to get the maximum and minimum allowable analog offset for a specific voltage range.

This function is invalid for ps4000 and ps5000.

get_channel_information(channel, info='ranges')[source]

This function queries which ranges are available on a scope device.

This function is invalid for ps5000 and ps6000.

Parameters
  • channel (enum.IntEnum) – 0=ChannelA, 1=ChannelB, …

  • info (enum.IntEnum, optional) – A ChannelInfo enum value or enum member name.

get_max_down_sample_ratio(num_unaggreated_samples, mode='None', segment_index=0)[source]
Returns

int – This function returns the maximum down-sampling ratio that can be used for a given number of samples in a given down-sampling mode.

get_max_segments()[source]

This function is valid for ps2000a, ps3000a, ps4000a and ps5000a.

Returns

int – This function returns the maximum number of segments allowed for the opened device. This number is the maximum value of nsegments that can be passed to memory_segments().

get_no_of_captures()[source]

This function finds out how many captures are available in rapid block mode after run_block() has been called when either the collection completed or the collection of waveforms was interrupted by calling stop(). The returned value (nCaptures) can then be used to iterate through the number of segments using get_values(), or in a single call to get_values_bulk() where it is used to calculate the toSegmentIndex parameter.

Not valid for ps5000.

get_num_of_processed_captures()[source]

This function finds out how many captures in rapid block mode have been processed after run_block() has been called when either the collection completed or the collection of waveforms was interrupted by calling stop(). The returned value (nCaptures) can then be used to iterate through the number of segments using get_values(), or in a single call to get_values_bulk() where it is used to calculate the toSegmentIndex parameter.

Not valid for ps4000 and ps5000.

get_streaming_latest_values(lp_ps)[source]

This function instructs the driver to return the next block of values to your StreamingReady callback. You must have previously called run_streaming() beforehand to set up streaming.

get_timebase(timebase, num_samples=0, segment_index=0, oversample=0)[source]

Since Python supports the float data type, this function returns get_timebase2(). The timebase that is returned is in seconds (not ns).

This function calculates the sampling rate and maximum number of samples for a given timebase under the specified conditions. The result will depend on the number of channels enabled by the last call to set_channel().

The oversample argument is only used by ps4000, ps5000 and ps6000.

get_timebase2(timebase, num_samples=0, segment_index=0, oversample=0)[source]

This function is an upgraded version of get_timebase(), and returns the time interval as a float rather than an int. This allows it to return sub-nanosecond time intervals. See get_timebase() for a full description.

The timebase that is returned is in seconds (not ns).

The oversample argument is only used by ps4000, ps5000 and ps6000.

get_trigger_time_offset(segment_index=0)[source]

This function gets the time, as two 4-byte values, at which the trigger occurred. Call it after block-mode data has been captured or when data has been retrieved from a previous block-mode capture. A 64-bit version of this function, get_trigger_time_offset64(), is also available.

get_trigger_time_offset64(segment_index=0)[source]

This function gets the time, as a single 64-bit value, at which the trigger occurred. Call it after block-mode data has been captured or when data has been retrieved from a previous block-mode capture. A 32-bit version of this function, get_trigger_time_offset(), is also available.

get_values(num_samples=None, start_index=0, factor=1, ratio_mode='None', segment_index=0)[source]

This function returns block-mode data, with or without down sampling, starting at the specified sample number. It is used to get the stored data from the driver after data collection has stopped.

Parameters
  • num_samples (int or None, optional) – The number of samples required. If None then automatically determine the number of samples to retrieve.

  • start_index (int, optional) – A zero-based index that indicates the start point for data collection. It is measured in sample intervals from the start of the buffer.

  • factor (int, optional) – The down-sampling factor that will be applied to the raw data.

  • ratio_mode (enum.IntEnum, optional) – Which down-sampling mode to use. A RatioMode enum.

  • segment_index (int, optional) – The zero-based number of the memory segment where the data is stored.

get_values_async(lp_data_ready, num_samples=None, start_index=0, factor=1, ratio_mode='None', segment_index=0)[source]

This function returns data either with or without down sampling, starting at the specified sample number. It is used to get the stored data from the scope after data collection has stopped. It returns the data using the lp_data_ready callback.

Parameters
  • lp_data_ready (callback) – A DataReady callback function.

  • num_samples (int, optional) – The number of samples required. If None then automatically determine the number of samples to retrieve.

  • start_index (int, optional) – A zero-based index that indicates the start point for data collection. It is measured in sample intervals from the start of the buffer.

  • factor (int, optional) – The downsampling factor that will be applied to the raw data.

  • ratio_mode (enum.IntEnum, optional) – Which down-sampling mode to use. A RatioMode enum.

  • segment_index (int, optional) – The zero-based number of the memory segment where the data is stored.

get_values_bulk(from_segment_index=0, to_segment_index=None, factor=1, ratio_mode='None')[source]

This function retrieves waveforms captured using rapid block mode. The waveforms must have been collected sequentially and in the same run.

The down_sample_ratio and down_sample_ratio_mode arguments are ignored for ps4000 and ps5000.

get_values_overlapped(start_index, down_sample_ratio, down_sample_ratio_mode, segment_index)[source]

This function allows you to make a deferred data-collection request, which will later be executed, and the arguments validated, when you call run_block() in block mode. The advantage of this function is that the driver makes contact with the scope only once, when you call run_block(), compared with the two contacts that occur when you use the conventional run_block(), get_values() calling sequence. This slightly reduces the dead time between successive captures in block mode.

This function is invalid for ps4000 and ps5000.

get_values_overlapped_bulk(start_index, down_sample_ratio, down_sample_ratio_mode, from_segment_index, to_segment_index)[source]

This function allows you to make a deferred data-collection request, which will later be executed, and the arguments validated, when you call run_block() in rapid block mode. The advantage of this method is that the driver makes contact with the scope only once, when you call run_block(), compared with the two contacts that occur when you use the conventional run_block(), get_values_bulk() calling sequence. This slightly reduces the dead time between successive captures in rapid block mode.

This function is invalid for ps4000 and ps5000.

get_values_trigger_time_offset_bulk(from_segment_index, to_segment_index)[source]

This function retrieves the time offsets, as lower and upper 32-bit values, for waveforms obtained in rapid block mode. This function is provided for use in programming environments that do not support 64- bit integers. If your programming environment supports this data type, it is easier to use get_values_trigger_time_offset_bulk64().

get_values_trigger_time_offset_bulk64(from_segment_index=0, to_segment_index=None)[source]

This function retrieves the 64-bit time offsets for waveforms captured in rapid block mode.

A 32-bit version of this function, get_values_trigger_time_offset_bulk(), is available for use with programming languages that do not support 64-bit integers

hold_off(holdoff, holdoff_type)[source]

This function is for backward compatibility only and is not currently used.

This function is only defined for ps2000a, ps3000a and ps4000.

is_led_flashing()[source]

This function reports whether or not the LED is flashing.

This function is supported by ps4000, ps4000a and ps5000.

is_trigger_or_pulse_width_qualifier_enabled()[source]

This function discovers whether a trigger, or pulse width triggering, is enabled.

memory_segments(num_segments)[source]

This function sets the number of memory segments that the scope will use. When the scope is opened, the number of segments defaults to 1, meaning that each capture fills the scopes available memory. This function allows you to divide the memory into a number of segments so that the scope can store several waveforms sequentially.

no_of_streaming_values()[source]

This function returns the number of samples available after data collection in streaming mode. Call it after calling stop().

open_unit(auto_select_power=True, resolution='8Bit')[source]

Open the PicoScope for communication.

This function opens a PicoScope attached to the computer. The maximum number of units that can be opened depends on the operating system, the kernel driver and the computer.

Parameters
  • auto_select_power (bool, optional) – PicoScopes that can be powered by either DC power or by USB power may raise PICO_POWER_SUPPLY_NOT_CONNECTED if the DC power supply is not connected. Passing in True will automatically switch to the USB power source.

  • resolution (str, optional) – The ADC resolution: 8, 12, 14, 15 or 16Bit. Only used by the PS5000A Series and it is ignored for all other PicoScope Series.

open_unit_async(auto_select_power=True, resolution='8Bit')[source]

This function opens a scope without blocking the calling thread. You can find out when it has finished by periodically calling open_unit_progress() until that function returns a value of 100.

Parameters
  • auto_select_power (bool, optional) – PicoScopes that can be powered by either DC power or by USB power may raise PICO_POWER_SUPPLY_NOT_CONNECTED if the DC power supply is not connected. Passing in True will automatically switch to the USB power source.

  • resolution (str, optional) – The ADC resolution: 8, 12, 14, 15 or 16Bit. Only used by the PS5000A Series and it is ignored for all other PicoScope Series.

open_unit_progress()[source]

This function checks on the progress of a request made to open_unit_async() to open a scope. The return value is from 0 to 100, where 100 implies that the operation is complete.

set_bandwidth_filter(channel, bandwidth)[source]

This function is reserved for future use.

This function is only valid for ps3000a, ps4000a and ps5000a.

set_data_buffer(channel, buffer=None, mode='None', segment_index=0)[source]

Set the data buffer for the specified channel.

The mode argument is ignored for ps4000 and ps5000. The segment_index argument is ignored for ps4000, ps5000 and ps6000.

Parameters
  • channel (enum.IntEnum) – An enum value or member name from Channel.

  • buffer (numpy.ndarray, optional) – A int16, numpy array. If None then use a pre-allocated array.

  • mode (enum.IntEnum, optional) – An enum value or member name from RatioMode.

  • segment_index (int, optional) – The zero-based number of the memory segment where the data is stored.

set_data_buffer_bulk(channel, buffer, waveform, mode='None')[source]

This function allows you to associate a buffer with a specified waveform number and input channel in rapid block mode. The number of waveforms captured is determined by the nCaptures argument sent to set_no_of_captures(). There is only one buffer for each waveform because the only down-sampling mode that requires two buffers, aggregation mode, is not available in rapid block mode. Call one of the GetValues functions to retrieve the data after capturing.

This function is only valid for ps4000, ps5000 and ps6000.

The down_sample_ratio_mode argument is ignored for ps4000 and ps5000.

set_data_buffers(channel, buffer_length, mode, segment_index)[source]

This function tells the driver where to store the data, either unprocessed or down sampled, that will be returned after the next call to one of the GetValues functions. The function allows you to specify only a single buffer, so for aggregation mode, which requires two buffers, you need to call set_data_buffers() instead.

You must allocate memory for the buffer before calling this function.

The mode argument is ignored for ps4000 and ps5000.

The segment_index argument is ignored for ps4000, ps5000 and ps6000.

set_digital_port(port, enabled, logic_level)[source]

This function is used to enable the digital port and set the logic level (the voltage at which the state transitions from 0 to 1).

This function is only used by ps2000a and ps3000a.

set_ets(mode, ets_cycles, ets_interleave)[source]

This function is used to enable or disable ETS (equivalent-time sampling) and to set the ETS parameters. See ETS overview for an explanation of ETS mode.

set_ets_time_buffer(buffer)[source]

This function tells the driver where to find your applications ETS time buffers. These buffers contain the 64-bit timing information for each ETS sample after you run a block-mode ETS capture.

Parameters

buffer (ctypes.c_longlong) – An array of 64-bit words (ctypes.c_int64), each representing the time, in picoseconds, at which the sample was captured.

set_ets_time_buffers(time_upper, time_lower)[source]

This function tells the driver where to find your applications ETS time buffers. These buffers contain the timing information for each ETS sample after you run a blockmode ETS capture. There are two buffers containing the upper and lower 32-bit parts of the timing information, to allow programming languages that do not support 64-bit data to retrieve the timings.

set_frequency_counter(channel, enabled, range, threshold_major, threshold_minor)[source]

This function is only define in the header file and it is not in the manual. This function is only valid for ps4000 and ps4000a.

set_no_of_captures(n_captures)[source]

This function sets the number of captures to be collected in one run of rapid block mode. If you do not call this function before a run, the driver will capture only one waveform. Once a value has been set, the value remains constant unless changed.

set_sig_gen_arbitrary(waveform, repetition_rate=None, offset_voltage=0.0, pk_to_pk=None, start_delta_phase=None, stop_delta_phase=None, delta_phase_increment=0, dwell_count=None, sweep_type='up', operation='off', index_mode='single', shots=None, sweeps=None, trigger_type='rising', trigger_source='None', ext_in_threshold=0)[source]

This function programs the signal generator to produce an arbitrary waveform.

Parameters
  • waveform (numpy.ndarray) – The arbitrary waveform, in volts.

  • repetition_rate (float, optional) – The requested repetition rate (frequency) of the entire arbitrary waveform. The actual repetition rate that is used may be different based on the specifications of the AWG. If specified then the sig_gen_frequency_to_phase() method is called to determine the value of start_delta_phase.

  • offset_voltage (float, optional) – The voltage offset, in volts, to be applied to the waveform.

  • pk_to_pk (float, optional) – The peak-to-peak voltage, in volts, of the waveform signal. If None then uses the maximum value of the waveform to determine the peak-to-peak voltage.

  • start_delta_phase (int, optional) – The initial value added to the phase accumulator as the generator begins to step through the waveform buffer.

  • stop_delta_phase (int, optional) – The final value added to the phase accumulator before the generator restarts or reverses the sweep. When frequency sweeping is not required, set equal to start_delta_phase.

  • delta_phase_increment (int, optional) – The amount added to the delta phase value every time the dwell_count period expires. This determines the amount by which the generator sweeps the output frequency in each dwell period. When frequency sweeping is not required, set to zero.

  • dwell_count (int, optional) – The time, in units of dacPeriod, between successive additions of delta_phase_increment to the delta phase accumulator. This determines the rate at which the generator sweeps the output frequency.

  • sweep_type (enum.IntEnum, optional) – Whether the frequency will sweep from start_frequency to stop_frequency, or in the opposite direction, or repeatedly reverse direction. One of: UP, DOWN, UPDOWN, DOWNUP

  • operation (enum.IntEnum, optional) – The type of waveform to be produced, specified by one of the following enumerated types (B models only): OFF, WHITENOISE, PRBS

  • index_mode (enum.IntEnum, optional) – Specifies how the signal will be formed from the arbitrary waveform data. Possible values are SINGLE or DUAL.

  • shots (int, optional) – If None then start and run continuously after trigger occurs.

  • sweeps (int, optional) – If None then start a sweep and continue after trigger occurs.

  • trigger_type (enum.IntEnum, optional) – The type of trigger that will be applied to the signal generator. One of: RISING, FALLING, GATE_HIGH, GATE_LOW.

  • trigger_source (enum.IntEnum, optional) – The source that will trigger the signal generator. If None then run without waiting for trigger.

  • ext_in_threshold (int, optional) – Used to set trigger level for external trigger.

Returns

numpy.ndarray – The arbitrary waveform, in ADU.

Raises

PicoTechError – If the value of an input parameter is invalid.

set_sig_gen_builtin(offset_voltage, pk_to_pk, wave_type, start_frequency, stop_frequency, increment, dwell_time, sweep_type, operation, shots, sweeps, trigger_type, trigger_source, ext_in_threshold)[source]

This function sets up the signal generator to produce a signal from a list of built-in waveforms. If different start and stop frequencies are specified, the device will sweep either up, down or up and down. Call set_sig_gen_builtin_v2() instead, which uses double-precision arguments.

set_sig_gen_builtin_v2(offset_voltage=0.0, pk_to_pk=1.0, wave_type='sine', start_frequency=1.0, stop_frequency=None, increment=0.1, dwell_time=1.0, sweep_type='up', operation='off', shots=None, sweeps=None, trigger_type='rising', trigger_source='None', ext_in_threshold=0)[source]

This function is an upgraded version of set_sig_gen_builtin() with double-precision frequency arguments for more precise control at low frequencies.

This function is invalid for ps4000 and ps4000a.

Parameters
  • offset_voltage (float, optional) – The voltage offset, in volts, to be applied to the waveform.

  • pk_to_pk (float, optional) – The peak-to-peak voltage, in volts, of the waveform signal.

  • wave_type (enum.IntEnum, optional) – The type of waveform to be generated. A WaveType enum.

  • start_frequency (float, optional) – The frequency that the signal generator will initially produce.

  • stop_frequency (float, optional) – The frequency at which the sweep reverses direction or returns to the initial frequency.

  • increment (float, optional) – The amount of frequency increase or decrease in sweep mode.

  • dwell_time (float, optional) – The time, in seconds, for which the sweep stays at each frequency.

  • sweep_type (enum.IntEnum, optional) – Whether the frequency will sweep from start_frequency to stop_frequency, or in the opposite direction, or repeatedly reverse direction. One of: UP, DOWN, UPDOWN, DOWNUP

  • operation (enum.IntEnum, optional) – The type of waveform to be produced, specified by one of the following enumerated types (B models only): OFF, WHITENOISE, PRBS

  • shots (int, optional) – If None then start and run continuously after trigger occurs.

  • sweeps (int, optional) – If None then start a sweep and continue after trigger occurs.

  • trigger_type (enum.IntEnum, optional) – The type of trigger that will be applied to the signal generator. One of: RISING, FALLING, GATE_HIGH, GATE_LOW.

  • trigger_source (enum.IntEnum, optional) – The source that will trigger the signal generator. If None then run without waiting for trigger.

  • ext_in_threshold (int, optional) – Used to set trigger level for external trigger.

set_sig_gen_properties_arbitrary(start_delta_phase, stop_delta_phase, delta_phase_increment, dwell_count, sweep_type, shots, sweeps, trigger_type, trigger_source, ext_in_threshold, offset_voltage=0, pk_to_pk=-1)[source]

This function reprograms the arbitrary waveform generator. All values can be reprogrammed while the signal generator is waiting for a trigger.

The offset_voltage and pk_to_pk arguments are only used for ps6000.

This function is invalid for ps4000 and ps5000.

set_sig_gen_properties_builtin(start_frequency, stop_frequency, increment, dwell_time, sweep_type, shots, sweeps, trigger_type, trigger_source, ext_in_threshold, offset_voltage=0, pk_to_pk=-1)[source]

This function reprograms the signal generator. Values can be changed while the signal generator is waiting for a trigger.

The offset_voltage and pk_to_pk arguments are only used for ps6000.

This function is invalid for ps4000 and ps5000.

set_simple_trigger(enable, source, threshold, direction, delay, auto_trigger_ms)[source]

This function simplifies arming the trigger. It supports only the LEVEL trigger types and does not allow more than one channel to have a trigger applied to it. Any previous pulse width qualifier is cancelled.

set_trigger_channel_directions(a='rising', b='rising', c='rising', d='rising', ext='rising', aux='rising')[source]

This function sets the direction of the trigger for each channel.

ps4000a overrides this method because it has a different implementation.

set_trigger_delay(delay)[source]

This function sets the post-trigger delay, which causes capture to start a defined time after the trigger event.

sig_gen_arbitrary_min_max_values()[source]

This function returns the range of possible sample values and waveform buffer sizes that can be supplied to set_sig_gen_arbitrary() for setting up the arbitrary waveform generator (AWG).

sig_gen_frequency_to_phase(repetition_rate, index_mode, buffer_length)[source]

This function converts a frequency to a phase count for use with the arbitrary waveform generator (AWG). The value returned depends on the length of the buffer, the index mode passed and the device model. The phase count can then be sent to the driver through set_sig_gen_arbitrary() or set_sig_gen_properties_arbitrary().

Parameters
  • repetition_rate (float) – The requested repetition rate (frequency) of the entire arbitrary waveform.

  • index_mode (enum.IntEnum) – An IndexMode enum value or member name.

  • buffer_length (int) – The size (number of samples) of the waveform.

Returns

int – The phase count.

Raises

PicoTechError – If the value of an input parameter is invalid.

sig_gen_software_control(state)[source]

This function causes a trigger event, or starts and stops gating. It is used when the signal generator is set to SOFT_TRIG.

trigger_within_pre_trigger_samples(state)[source]

This function is in the header file, but it is not in the manual.

This function is only valid for ps4000 and ps5000a.

set_trigger_channel_conditions(conditions, info='clear')[source]

This function sets up trigger conditions on the scope’s inputs. The trigger is defined by one or more TriggerConditions structures, which are found in the structs module, that are then ORed together. Each structure is itself the AND of the states of one or more of the inputs. This AND-OR logic allows you to create any possible Boolean function of the scope’s inputs.

The info parameter is only used for ps4000a and it is a PS4000AConditionsInfo enum.

set_trigger_channel_properties(channel_properties, timeout=0.1, aux_output_enable=0)[source]

This function is used to enable or disable triggering and set its parameters.

Parameters
  • channel_properties (list of TriggerChannelProperties structs) – A list of TriggerChannelProperties structures describing the requested properties.

  • timeout (float, optional) – The time, in seconds, for which the scope device will wait before collecting data if no trigger event occurs. If this is set to zero, the scope device will wait indefinitely for a trigger.

  • aux_output_enable (int, optional) – Zero configures the AUXIO connector as a trigger input. Any other value configures it as a trigger output. Only used by ps5000.