PicoScope 3000E Series psospa API

https://www.picotech.com/helpfiles/psospa-api/
Admin
PicoScope 3000E Series psospa API is a programmer's guide and C-based API for controlling Pico...
Tokens:74,518
Snippets:754
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Configure Device for Rapid Block Mode with Aggregation

Source: https://www.picotech.com/helpfiles/psospa-api/rapidblockmodeexample2.html

Sets up the device for rapid block mode, specifying the number of captures and initiating the block capture. The setup is identical whether aggregation is used or not.

```c
#define MAX_WAVEFORMS 100
#define MAX_SAMPLES 1000
// set the number of waveforms to MAX_WAVEFORMS
psospaSetNoOfCaptures(handle, MAX_WAVEFORMS);
psospaRunBlock
(
handle,
0, // noOfPreTriggerSamples,
1000000, // noOfPostTriggerSamples,
400, // sample interval in picoseconds,
&timeIndisposedMs,
0, // first segment index to be captured,
lpReady,
&pParameter
);
```

--------------------------------

### Example of Combined Status Flags

Source: https://www.picotech.com/helpfiles/psospa-api/pico_trigger_info.html

Illustrates how multiple status flags can be combined using a logical OR operation.

```c
For example the value 0x03000001 is a combination of:
PICO_DEVICE_TIME_STAMP_RESET bit or'ed with PICO_TRIGGER_TIME_NOT_REQUESTED
```

--------------------------------

### psospaSigGenTrigger

Source: https://www.picotech.com/helpfiles/psospa-api/psospasiggentrigger.html

Sets up triggering for the signal generator, allowing it to start and stop based on a signal or event. After configuration, call psospaSigGenApply() to apply settings.

```APIDOC
## psospaSigGenTrigger

### Description
This function sets up triggering for the signal generator. This feature causes the signal generator to start and stop under the control of a signal or event. After configuring all required signal generator settings, call psopaSigGenApply() to apply them to the device.

### Applicability
All modes

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **triggerType** (PICO_SIGGEN_TRIG_TYPE) - Specifies the trigger type: PICO_SIGGEN_RISING (0), PICO_SIGGEN_FALLING (1), PICO_SIGGEN_GATE_HIGH (2), PICO_SIGGEN_GATE_LOW (3).
- **triggerSource** (PICO_SIGGEN_TRIG_SOURCE) - The signal used as a trigger: PICO_SIGGEN_NONE (0), PICO_SIGGEN_SCOPE_TRIG (1), PICO_SIGGEN_AUX_IN (2), PICO_SIGGEN_SOFT_TRIG (4).
- **cycles** (uint64_t) - The number of waveform cycles to generate after the trigger. Set to zero for indefinite generation.
- **autoTriggerPicoSeconds** (uint64_t) - Reserved for future use, set to zero.

### Returns
- **PICO_OK**: Operation successful.
- **PICO_SIGGEN_TRIGGERTYPE_NOT_SUPPORTED**: The provided trigger type is not supported.
- **PICO_SIGGEN_TRIGGERSOURCE_NOT_SUPPORTED**: The provided trigger source is not supported.
- **PICO_SIGGEN_CYCLES_OUT_OF_RANGE**: The provided cycles value exceeds the maximum allowed value.
```

--------------------------------

### PicoUpdateFirmwareProgress Callback Function

Source: https://www.picotech.com/helpfiles/psospa-api/picoupdatefirmwareprogress.html

The PicoUpdateFirmwareProgress callback function is used to get the status of a firmware update. You should write this callback function and register it with the driver using psospaStartFirmwareUpdate(). The driver calls it back when the firmware update status changes.

```APIDOC
## PicoUpdateFirmwareProgress Callback

### Description
This callback function is invoked by the driver to report the progress of a firmware update. It allows your application to monitor the status of the update process.

### Signature
```c
typedef void (* PicoUpdateFirmwareProgress)(
  int16_t handle,
  uint16_t progress
);
```

### Purpose
To provide real-time feedback on the firmware update progress. This callback should be registered with the driver using `psospaStartFirmwareUpdate()`.

### Arguments
- **handle** (int16_t) - The device identifier returned by `psospaOpenUnit()`.
- **progress** (uint16_t) - A progress indicator, typically a percentage or status code.

### Returns
Nothing.

### Applicability
All modes.
```

--------------------------------

### psospaGetValuesAsync

Source: https://www.picotech.com/helpfiles/psospa-api/psospagetvaluesasync.html

Obtains data from the oscilloscope, with downsampling if requested, starting at the specified sample number. It delivers the data using a callback function.

```APIDOC
## psospaGetValuesAsync

### Description
This function obtains data from the oscilloscope, with downsampling if requested, starting at the specified sample number. It delivers the data using a callback.

Applicable in Streaming mode and Block mode.

### Arguments
- **handle** (int16_t): Identifier for the device.
- **startIndex** (uint64_t): The starting index for data retrieval.
- **noOfSamples** (uint64_t): The number of samples to retrieve.
- **downSampleRatio** (uint64_t): The ratio for downsampling.
- **downSampleRatioMode** (PICO_RATIO_MODE): The mode for downsampling ratio.
- **segmentIndex** (uint64_t): The index of the segment to retrieve data from.
- **lpDataReady** (PICO_POINTER): A pointer to the user-supplied psospaDataReady() callback function that will be called when the data is ready.
- **pParameter** (PICO_POINTER): A void pointer that will be passed to the callback function. The data type is determined by the application.

### Returns
- **PICO_OK**: Operation successful.
- **PICO_NO_SAMPLES_AVAILABLE**: No samples are available.
- **PICO_DEVICE_SAMPLING**: The device is currently sampling.
- **PICO_NULL_PARAMETER**: A required parameter is null.
- **PICO_STARTINDEX_INVALID**: The startIndex is invalid.
- **PICO_SEGMENT_OUT_OF_RANGE**: The segmentIndex is out of range.
- **PICO_INVALID_PARAMETER**: An invalid parameter was provided.
- **PICO_DATA_NOT_AVAILABLE**: Data is not available.
- **PICO_INVALID_SAMPLERATIO**: The downSampleRatio is invalid.
- **PICO_INVALID_CALL**: The function was called incorrectly.
```

--------------------------------

### psospaRunStreaming

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psosparunstreaming.html=

Starts data collection in streaming mode. The device can return either raw or downsampled data. Use psospaGetStreamingLatestValues() to retrieve the data.

```APIDOC
## psospaRunStreaming

### Description
This function tells the oscilloscope to start collecting data in streaming mode. The device can return either raw or downsampled data to your application while streaming is in progress. Call psospaGetStreamingLatestValues() to retrieve the data. See Using streaming mode for a step-by-step guide to this process.

When a trigger is set, the total number of samples is the sum of maxPreTriggerSamples and maxPostTriggerSamples. If autoStop is false then this will become the maximum number of samples without downsampling.

When downsampled data is returned, the raw samples remain stored on the device. The maximum number of raw samples that can be retrieved after streaming has stopped is (scope's memory size) / (resolution data size * channels), where channels is the number of active channels rounded up to a power of 2.

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **sampleInterval** (double *) - On entry, the requested time interval between samples; on exit, the actual time interval used.
- **sampleIntervalTimeUnits** (PICO_TIME_UNITS) - The unit of time used for sampleInterval. Use one of these values: PICO_FS, PICO_PS, PICO_NS, PICO_US, PICO_MS, PICO_S.
- **maxPreTriggerSamples** (uint64_t) - The maximum number of raw samples before a trigger event for each enabled channel. If no trigger condition is set this argument is ignored.
- **maxPostTriggerSamples** (uint64_t) - The maximum number of raw samples after a trigger event for each enabled channel. If no trigger condition is set, this argument states the maximum number of samples to be stored.
- **autoStop** (int16_t) - A flag that specifies if the streaming should stop when all of maxSamples have been captured.
- **downSampleRatio** (uint64_t) - See psospaGetValues().
- **downSampleRatioMode** (PICO_RATIO_MODE) - See psospaGetValues().

### Returns
- **PICO_OK**
- **PICO_NULL_PARAMETER**
- **PICO_INVALID_PARAMETER**
- **PICO_STREAMING_FAILED**
- **PICO_TRIGGER_ERROR**
- **PICO_INVALID_SAMPLE_INTERVAL**
- **PICO_INVALID_BUFFER**
- **PICO_FW_FAIL**
- **PICO_MEMORY**
- **PICO_SIGGEN_GATING_AUXIO_ENABLED** (signal generator is set to trigger on AUX input with incompatible trigger type)
- **PICO_HARDWARE_CAPTURING_CALL_STOP**
- **PICO_STREAMING_COMBINATION_OF_RAW_DATA_AND_ONE_AGGREGATION_DATA_TYPE_ALLOWED**
- **PICO_TIME_UNITS_OUT_OF_RANGE**
- **PICO_NO_SAMPLES_REQUESTED**
- **PICO_TOO_FEW_REQUESTED_STREAMING_SAMPLES**
- **PICO_TOO_MANY_SAMPLES**
- **PICO_NOT_USED_IN_THIS_CAPTURE_MODE**
- **PICO_INVALID_RATIO_MODE**
- **PICO_STREAMING_DOES_NOT_SUPPORT_TRIGGER_RATIO_MODES**
- **PICO_RATIO_MODE_NOT_SUPPORTED**
- **PICO_THRESHOLD_UPPER_LOWER_MISMATCH**
- **PICO_TRIGGER_CHANNEL_NOT_ENABLED**
- **PICO_CONDITION_HAS_NO_TRIGGER_PROPERTY**
- **PICO_INVALID_DIGITAL_PORT**
- **PICO_TRIGGER_PORT_NOT_ENABLED**
- **PICO_DIGITAL_DIRECTION_NOT_SET**
- **PICO_WARNING_AUX_OUTPUT_CONFLICT**
- **PICO_READ_SELECTION_OUT_OF_RANGE**
- **PICO_RATIO_MODE_TRIGGER_MASKING_INVALID**
- **PICO_USE_THE_TRIGGER_READ**
- **PICO_USE_A_DATA_READ**
- **PICO_RATIO_MODE_REQUIRES_NUMBER_OF_SAMPLES_TO_BE_SET**
- **PICO_OPERATION_FAILED**
- **PICO_ARGUMENT_OUT_OF_RANGE**
- **PICO_BUFFERS_NOT_SET**
- **PICO_STREAMING_ONLY_SUPPORTS_ONE_READ**
- **PICO_NOT_RESPONDING_OVERHEATED**
- **PICO_ENDPOINT_MISSING**
- **PICO_UNKNOWN_ENDPOINT_REQUEST**
```

--------------------------------

### psospaRunBlock

Source: https://www.picotech.com/helpfiles/psospa-api/psosparunblock.html

Starts collecting data in block mode. The number of samples is determined by noOfPreTriggerSamples and noOfPostTriggerSamples. The total number of samples must not exceed the size of the specified memory segment.

```APIDOC
## psospaRunBlock

### Description
This function starts collecting data in block mode. For a step-by-step guide to this process, see Using block mode.

The number of samples is determined by noOfPreTriggerSamples and noOfPostTriggerSamples. The total number of samples must not be more than the size of the segment referred to by segmentIndex.

### Applicability
Block mode, rapid block mode

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **noOfPreTriggerSamples** (uint64_t) - The number of samples to return before the trigger event. If no trigger has been set, then this argument is added to noOfPostTriggerSamples to give the maximum number of data points (samples) to collect.
- **noOfPostTriggerSamples** (uint64_t) - The number of samples to return after the trigger event. If no trigger event has been set, then this argument is added to noOfPreTriggerSamples to give the maximum number of data points to collect. If a trigger condition has been set, this specifies the number of data points to collect after a trigger has fired, and the number of samples to be collected is: noOfPreTriggerSamples + noOfPostTriggerSamples.
- **timebase** (uint32_t) - A number, indicating the sample interval, in picoseconds. See the guide to calculating timebase values. If the value you pass does not correspond to a valid sampling rate for the current scope setup, the scope will select the nearest available sampling rate. It is recommended to call psospaNearestSampleIntervalStateless() to determine a valid sample interval before calling this function.
- **timeIndisposedMs** (double *) - On exit, the time in milliseconds that the scope will spend collecting samples. This does not include any auto trigger timeout. If this pointer is null, nothing will be written here.
- **segmentIndex** (uint64_t) - Zero-based, specifies which memory segment to use.
- **lpReady** (psospaBlockReady) - A pointer to the psospaBlockReady() callback function that the driver will call when the data has been collected. To use the psospaIsReady() polling method instead of a callback function, set this pointer to NULL.
- **pParameter** (PICO_POINTER) - A void pointer that is passed to the psospaBlockReady() callback function. The callback can use this pointer to return arbitrary data to the application.

### Returns
- **PICO_OK**
- **PICO_SEGMENT_OUT_OF_RANGE**
- **PICO_INVALID_CHANNEL**
- **PICO_INVALID_TRIGGER_CHANNEL**
- **PICO_INVALID_CONDITION_CHANNEL**
- **PICO_TOO_MANY_SAMPLES**
- **PICO_INVALID_TIMEBASE**
- **PICO_CONFIG_FAIL**
- **PICO_INVALID_PARAMETER**
- **PICO_TRIGGER_ERROR**
- **PICO_FW_FAIL**
- **PICO_PULSE_WIDTH_QUALIFIER**
- **PICO_SEGMENT_OUT_OF_RANGE** (in Overlapped mode)
- **PICO_STARTINDEX_INVALID** (in Overlapped mode)
- **PICO_INVALID_SAMPLERATIO** (in Overlapped mode)
- **PICO_CONFIG_FAIL**
- **PICO_SIGGEN_GATING_AUXIO_ENABLED** (signal generator is set to trigger on AUX input with incompatible trigger type)
```

--------------------------------

### psospaGetValues

Source: https://www.picotech.com/helpfiles/psospa-api/psospagetvalues.html

Retrieves data, either with or without downsampling, starting at the specified sample number. It is used to get the stored data from the scope after data collection has stopped, and store it in a user buffer previously passed to psospaSetDataBuffer() or psospaSetDataBuffers(). It blocks the calling function while retrieving data.

```APIDOC
## psospaGetValues

### Description
Retrieves data, either with or without downsampling, starting at the specified sample number. It is used to get the stored data from the scope after data collection has stopped, and store it in a user buffer previously passed to psospaSetDataBuffer() or psospaSetDataBuffers(). It blocks the calling function while retrieving data.

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **startIndex** (uint64_t) - A zero-based index that indicates the start point for data collection. It is measured in sample intervals from the start of the buffer.
- **noOfSamples** (uint64_t *) - On entry, the number of raw samples to be processed. On exit, the actual number retrieved. The number of samples retrieved will not be more than the number requested, and the data retrieved always starts with the first sample captured.
- **downSampleRatio** (uint64_t) - The downsampling factor that will be applied to the raw data. Must be greater than zero.
- **downSampleRatioMode** (PICO_RATIO_MODE) - Which downsampling mode to use. The available values are:
  - PICO_RATIO_MODE_AGGREGATE
  - PICO_RATIO_MODE_DECIMATE
  - PICO_RATIO_MODE_AVERAGE
  - PICO_RATIO_MODE_TRIGGER - cannot be combined with any other ratio mode
  - PICO_RATIO_MODE_RAW
- **segmentIndex** (uint64_t) - The zero-based number of the memory segment where the data is stored.
- **overflow** (int16_t *) - On exit, a set of flags that indicate whether an overvoltage has occurred on any of the channels. It is a bit field with bit 0 denoting Channel A.

### Returns
- PICO_OK
- PICO_NO_SAMPLES_AVAILABLE
- PICO_DEVICE_SAMPLING
- PICO_NULL_PARAMETER
- PICO_SEGMENT_OUT_OF_RANGE
- PICO_INVALID_PARAMETER
- PICO_TOO_MANY_SAMPLES
- PICO_DATA_NOT_AVAILABLE
- PICO_STARTINDEX_INVALID
- PICO_INVALID_SAMPLERATIO
- PICO_INVALID_CALL
- PICO_MEMORY
- PICO_RATIO_MODE_NOT_SUPPORTED
```

--------------------------------

### Opening Multiple Units and Running Data Collection

Source: https://www.picotech.com/helpfiles/psospa-api/multiunitoperation.html

Demonstrates how to open handles for multiple oscilloscopes, configure their channels, initiate block data collection, and check for readiness.

```APIDOC
## Combining Several Oscilloscopes

It is possible to collect data using up to 64 PicoScope 3000E Series oscilloscopes at the same time, depending on the capabilities of the PC. Each oscilloscope must be connected to a separate USB port. The `psospaOpenUnit()` function returns a handle to an oscilloscope. All the other functions require this handle for oscilloscope identification. For example, to collect data from two oscilloscopes at the same time:

```c
CALLBACK psospaBlockReady(...)
// define callback function specific to application
handle1 = psospaOpenUnit()
handle2 = psospaOpenUnit()
psospaSetChannelOn(handle1)
// set up unit 1
psospaRunBlock(handle1)
psospaSetChannelOn(handle2)
// set up unit 2
psospaRunBlock(handle2)
// data will be stored in buffers 
// and application will be notified using callback
ready = FALSE
while not ready
ready = handle1_ready
ready &= handle2_ready
```

**Note:** A trigger may be fed into the Aux Trig (AUX I/O) input to provide some degree of synchronization between multiple oscilloscopes.
```

--------------------------------

### psospaSetTriggerDelay

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospasettriggerdelay.html=

Sets the post-trigger delay, causing capture to start a defined time after the trigger event.

```APIDOC
## psospaSetTriggerDelay

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

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **delay** (uint64_t) - The time between the trigger event occurring and the first post-trigger sample being captured. For example, if delay=100, the post-trigger samples will be counted starting 100 sample periods after the trigger event. At a timebase of 5 GS/s, or 200 ps per sample, the delay would be 100 x 200 ps = 20 ns. If pre-trigger samples are requested, these are immediately preceding the post-trigger samples, i.e. overlapping with the trigger delay time.

### Returns
- PICO_OK
```

--------------------------------

### Set Up Data Buffers for Aggregation

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?rapidblockmodeexample2.html=

Configures data buffers for each channel to store aggregated maximum and minimum samples. The buffer sizes are set to MAX_SAMPLES.

```c
PICO_ACTION action = PICO_CLEAR_ALL | PICO_ADD;
for (int32_t c = PICO_CHANNEL_A; c <= PICO_CHANNEL_D; c++)
{
  psospaSetDataBuffers
  (
    handle,
    c,
    bufferMax[c],
    bufferMin[c]
    MAX_SAMPLES,
    PICO_INT16_T,
    0,
    PICO_RATIO_MODE_AGGREGATE,
    action
  );
  action = PICO_ADD;
}
```

--------------------------------

### Run Block Capture

Source: https://www.picotech.com/helpfiles/psospa-api/rapidblockmodeexample1.html

Initiates a block capture operation. Configure pre-trigger samples, post-trigger samples, sample interval, and callback functions.

```c
psospaRunBlock
(
handle,
0, // noOfPreTriggerSamples
10000, // noOfPostTriggerSamples
400, // sample interval in picoseconds
&timeIndisposedMs,
0, // first segment index to capture
lpReady,
&pParameter
);
```

--------------------------------

### psospaStopUsingGetValuesOverlapped

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospastopusinggetvaluesoverlapped.html=

Stops deferred data-collection that was started by calling psospaGetValuesOverlapped(). This function is applicable in block and rapid block modes.

```APIDOC
## psospaStopUsingGetValuesOverlapped

### Description
Stops deferred data-collection that was started by calling psospaGetValuesOverlapped().

### Applicability
- Block mode
- Rapid block mode

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().

### Returns
- PICO_OK
```

--------------------------------

### Wait for Callback and Set Data Buffers

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?rapidblockmodeexample1.html=

Waits for the callback function to signal completion and then sets up data buffers for each channel and segment. The 'action' flag is updated after the first buffer is set.

```c
while (!pParameter) Sleep (0);
PICO_ACTION action = PICO_CLEAR_ALL | PICO_ADD;
int32_t first_segment_to_read = 10;
for (int32_t i = 0; i < 10; i++)
{
  for (int32_t c = PICO_CHANNEL_A; c <= PICO_CHANNEL_D; c++)
  {
    psospaSetDataBuffer
    (
      handle,
      c,
      buffer[c][i],
      MAX_SAMPLES,
      PICO_INT16_T,
      first_segment_to_read + i,
      PICO_RATIO_MODE_RAW,
      action
    );
    action = PICO_ADD;
  }
}
```

--------------------------------

### Run Device in Block Mode for Aggregation

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?rapidblockmodeexample2.html=

Initiates the device to run in block mode. This configuration is the same whether or not aggregation will be used when retrieving samples.

```c
pParameter = false;
psospaRunBlock
(
  handle,
  0, // noOfPreTriggerSamples,
  1000000, // noOfPostTriggerSamples,
  400, // sample interval in picoseconds,
  &timeIndisposedMs,
  0, // first segment index to be captured,
  lpReady,
  &pParameter
);
```

--------------------------------

### Open and Configure Multiple Oscilloscopes

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?multiunitoperation.html=

Opens handles for two oscilloscopes and configures them for data collection. Ensure each oscilloscope is connected to a separate USB port. The `psospaOpenUnit()` function returns a handle, which is then used by other functions.

```c
CALLBACK psospaBlockReady(...)
// define callback function specific to application
handle1 = psospaOpenUnit()
handle2 = psospaOpenUnit()
psospaSetChannelOn(handle1)
// set up unit 1
psospaRunBlock(handle1)
psospaSetChannelOn(handle2)
// set up unit 2
psospaRunBlock(handle2)
// data will be stored in buffers 
// and application will be notified using callback
ready = FALSE
while not ready
ready = handle1_ready
ready &= handle2_ready
```

--------------------------------

### psospaRunBlock

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psosparunblock.html=

Starts collecting data in block mode. This function configures the device to capture a specified number of pre-trigger and post-trigger samples based on the provided timebase and segment.

```APIDOC
## psospaRunBlock

### Description
Starts collecting data in block mode. The number of samples is determined by `noOfPreTriggerSamples` and `noOfPostTriggerSamples`. The total number of samples must not exceed the size of the segment specified by `segmentIndex`.

### Applicability
Block mode, rapid block mode

### Arguments
- **handle** (int16_t) - The device identifier returned by `psospaOpenUnit()`.
- **noOfPreTriggerSamples** (uint64_t) - The number of samples to return before the trigger event. If no trigger is set, this is added to `noOfPostTriggerSamples` for the maximum data points.
- **noOfPostTriggerSamples** (uint64_t) - The number of samples to return after the trigger event. If no trigger is set, this is added to `noOfPreTriggerSamples`. If a trigger is set, this specifies samples after the trigger fires. Total samples = `noOfPreTriggerSamples` + `noOfPostTriggerSamples`.
- **timebase** (uint32_t) - The sample interval in picoseconds. If the value is invalid, the scope selects the nearest available rate. It is recommended to use `psospaNearestSampleIntervalStateless()` to find a valid interval.
- **timeIndisposedMs** (double *) - On exit, the time in milliseconds the scope spends collecting samples (excluding auto-trigger timeout). If NULL, this value is not written.
- **segmentIndex** (uint64_t) - Zero-based index specifying the memory segment to use.
- **lpReady** (psospaBlockReady) - A pointer to the `psospaBlockReady()` callback function called when data is collected. Set to NULL to use `psospaIsReady()` polling instead.
- **pParameter** (PICO_POINTER) - A void pointer passed to the `psospaBlockReady()` callback function for returning arbitrary data.

### Returns
- **PICO_OK**: Operation successful.
- **PICO_SEGMENT_OUT_OF_RANGE**: The specified segment index is out of range.
- **PICO_INVALID_CHANNEL**: An invalid channel was specified.
- **PICO_INVALID_TRIGGER_CHANNEL**: An invalid trigger channel was specified.
- **PICO_INVALID_CONDITION_CHANNEL**: An invalid condition channel was specified.
- **PICO_TOO_MANY_SAMPLES**: The requested number of samples exceeds the segment size.
- **PICO_INVALID_TIMEBASE**: The provided timebase value is invalid.
- **PICO_CONFIG_FAIL**: Configuration of the device failed.
- **PICO_INVALID_PARAMETER**: An invalid parameter was provided.
- **PICO_TRIGGER_ERROR**: An error occurred with the trigger setup.
- **PICO_FW_FAIL**: Firmware operation failed.
- **PICO_PULSE_WIDTH_QUALIFIER**: An issue with pulse width qualifier settings.
- **PICO_SEGMENT_OUT_OF_RANGE** (in Overlapped mode): Segment out of range in Overlapped mode.
- **PICO_STARTINDEX_INVALID** (in Overlapped mode): Invalid start index in Overlapped mode.
- **PICO_INVALID_SAMPLERATIO** (in Overlapped mode): Invalid sample ratio in Overlapped mode.
- **PICO_SIGGEN_GATING_AUXIO_ENABLED**: Signal generator is set to trigger on AUX input with an incompatible trigger type.
```

--------------------------------

### Get Values in Bulk

Source: https://www.picotech.com/helpfiles/psospa-api/rapidblockmodeexample1.html

Retrieves data in bulk from specified segments without aggregation. This function populates indices 0 to 9 with data from segments 10 to 19.

```c
psospaGetValuesBulk
(
handle,
0,|  // startIndex  
&noOfSamples, // set to MAX_SAMPLES on entering the function
10, // fromSegmentIndex
19, // toSegmentIndex
1, // downsampling ratio
PICO_RATIO_MODE_RAW,  // downsampling ratio mode
overflow // indices 0 to 9 will be populated (index always starts from 0)
)
```

--------------------------------

### psospaDataReady Function Details

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospadataready.html=

Detailed explanation of the psospaDataReady callback function, its arguments, and its purpose in collecting data from the PICO driver.

```APIDOC
## psospaDataReady Callback

### Description
This is a callback function that you write to collect data from the driver. You supply a pointer to the function when you call psospaGetValuesAsync() and the driver calls your function back when the data is ready.

### Applicability
All modes

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **status** (PICO_STATUS) - A PICO_STATUS code returned by the driver.
- **noOfSamples** (uint64_t) - The number of samples collected.
- **overflow** (int16_t) - A set of flags that indicates whether an overvoltage has occurred and on which channels. It is a bit field with bit 0 representing Channel A.
- **pParameter** (PICO_POINTER) - A void pointer passed from psospaGetValuesAsync(). The callback function can write to this location to send any data, such as a status flag, back to the application. The data type is defined by the application programmer.

### Returns
Nothing
```

--------------------------------

### PicoUpdateFirmwareProgress Callback Function

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?picoupdatefirmwareprogress.html=

The PicoUpdateFirmwareProgress callback function is invoked by the driver to report the progress of a firmware update. You should implement this function and register it with psospaStartFirmwareUpdate().

```APIDOC
## PicoUpdateFirmwareProgress Callback

### Description
This callback function is used to get the status of a firmware update. The driver calls this function back when the firmware update status changes.

### Signature
typedef void (* PicoUpdateFirmwareProgress)(
int16_t handle,
uint16_t progress
)

### Parameters
#### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **progress** (uint16_t) - A progress indicator for the firmware update.

### Returns
- nothing
```

--------------------------------

### Configure Device for Aggregation

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?rapidblockmodeexample2.html=

Sets the number of captures for the device before running in block mode. This should be equal to or more than the number of captures required.

```c
#define MAX_WAVEFORMS 100
#define MAX_SAMPLES 1000

// set the number of waveforms to MAX_WAVEFORMS
psospaSetNoOfCaptures(handle, MAX_WAVEFORMS);
```

--------------------------------

### Set Data Buffers for Multiple Segments

Source: https://www.picotech.com/helpfiles/psospa-api/rapidblockmodeexample1.html

Configures data buffers for multiple channels and segments. Each buffer is set to hold MAX_SAMPLES. The 'action' parameter controls whether to clear existing buffers or add new ones.

```c
#define MAX_SAMPLES 1000
// ... other definitions ...
int32_t first_segment_to_read = 10;
PICO_ACTION action = PICO_CLEAR_ALL | PICO_ADD;
for (int32_t i = 0; i < 10; i++)
{
for (int32_t c = PICO_CHANNEL_A; c <= PICO_CHANNEL_D; c++)
{
psospaSetDataBuffer
(
handle,
c,
buffer[c][i],
MAX_SAMPLES,
PICO_INT16_T,
first_segment_to_read + i,
PICO_RATIO_MODE_RAW,
action
);
action = PICO_ADD;
}
}
```

--------------------------------

### psospaGetTriggerTimeOffset

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospagettriggertimeoffset.html=

Retrieves the trigger time offset for waveforms. This offset is an adjustment value used for correcting jitter in the waveform and should be added to the nominal trigger time to get the corrected trigger time. Call this function after data has been captured or retrieved.

```APIDOC
## psospaGetTriggerTimeOffset

### Description
Gets the trigger time offset for waveforms obtained in block mode or rapid block mode. This offset is used for correcting jitter in the waveform and should be added to the nominal trigger time to get the corrected trigger time. This function should be called after data has been captured or retrieved.

### Signature
PICO_STATUS psospaGetTriggerTimeOffset(
  int16_t handle,
  int64_t * time,
  PICO_TIME_UNITS * timeUnits,
  uint64_t segmentIndex
)

### Parameters
#### Path Parameters
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **time** (int64_t *) - On exit, the time at which the trigger point occurred.
- **timeUnits** (PICO_TIME_UNITS *) - On exit, the time units in which time is measured. Possible values include PICO_FS, PICO_PS, PICO_NS, PICO_US, PICO_MS, PICO_S.
- **segmentIndex** (uint64_t) - The number of the memory segment for which the information is required.

### Returns
- **PICO_OK**: Success.
- **PICO_DEVICE_SAMPLING**: Device is sampling.
- **PICO_SEGMENT_OUT_OF_RANGE**: The specified segment index is out of range.
- **PICO_NULL_PARAMETER**: A null pointer was passed as an argument.
- **PICO_NO_SAMPLES_AVAILABLE**: No samples are available for the specified segment.
- **PICO_TRIGGER_TIME_NOT_REQUESTED**: Trigger time data was not requested during capture.
```

--------------------------------

### psospaSetPulseWidthQualifierProperties

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospasetpulsewidthqualifierproperties.html=

This function sets the parameters for the pulse width time qualifier. The pulse width timer resets upon an event matching user conditions, marking the start of a 'pulse'. The qualifier becomes true when the time since the most recent start-of-pulse event meets the conditions set by this function (e.g., less than 100 sample intervals ago).

```APIDOC
## psospaSetPulseWidthQualifierProperties

### Description
Sets parameters for the pulse width time qualifier, an optional input to the triggering condition.

### Function Signature
PICO_STATUS psospaSetPulseWidthQualifierProperties(
  int16_t handle,
  uint32_t lower,
  uint32_t upper,
  PICO_PULSE_WIDTH_TYPE type
)

### Arguments
* **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
* **lower** (uint32_t) - The lower pulse width threshold in sample intervals.
* **upper** (uint32_t) - The upper pulse width threshold in sample intervals.
* **type** (PICO_PULSE_WIDTH_TYPE) - The pulse width qualifier type:
    * PICO_PW_TYPE_NONE (0): No pulse width qualifier required.
    * PICO_PW_TYPE_LESS_THAN (1): Pulse width must be less than the threshold.
    * PICO_PW_TYPE_GREATER_THAN (2): Pulse width must be greater than the threshold.
    * PICO_PW_TYPE_IN_RANGE (3): Pulse width must be between two thresholds.
    * PICO_PW_TYPE_OUT_OF_RANGE (4): Pulse width must not be between two thresholds.

### Returns
* PICO_OK
* PICO_NULL_PARAMETER
```

--------------------------------

### PicoUpdateFirmwareProgress Callback Signature

Source: https://www.picotech.com/helpfiles/psospa-api/picoupdatefirmwareprogress.html

This is the function signature for the PicoUpdateFirmwareProgress callback. You must implement this function and register it with psospaStartFirmwareUpdate() to receive firmware update status notifications.

```c
typedef void (* PicoUpdateFirmwareProgress)
(
int16_t handle,
uint16_t progress
)
```

--------------------------------

### psospaSigGenApply

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospasiggenapply.html=

Sets the signal generator running using parameters previously configured by other psospaSigGen... functions.

```APIDOC
## psospaSigGenApply

### Description
Sets the signal generator running using parameters previously configured by the other psospaSigGen... functions.

### Function Signature
PICO_STATUS psospaSigGenApply(
  int16_t handle,
  int16_t sigGenEnabled,
  int16_t sweepEnabled,
  int16_t triggerEnabled,
  double * frequency,
  double * stopFrequency,
  double * frequencyIncrement,
  double * dwellTime
)

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **sigGenEnabled** (int16_t) - Switches the signal generator on (1) or off (0).
- **sweepEnabled** (int16_t) - Switches sweep mode on (1) or off (0).
- **triggerEnabled** (int16_t) - Switches triggering of the signal generator on (1) or off (0).
- **frequency** (double *) - On exit, the actual achieved signal generator frequency (or start frequency in sweep mode).
- **stopFrequency** (double *) - On exit, the actual achieved signal generator frequency at the end of the sweep.
- **frequencyIncrement** (double *) - On exit, the actual achieved frequency step size in sweep mode.
- **dwellTime** (double *) - On exit, the actual achieved time in seconds between frequency steps in sweep mode.

### Returns
- **PICO_OK**
- **PICO_WARNING_AUX_OUTPUT_CONFLICT** - Indicates a conflict with the auxiliary output.
- **PICO_BUSY** - Indicates that the device is busy.
```

--------------------------------

### psospaDataReady Callback Function Arguments

Source: https://www.picotech.com/helpfiles/psospa-api/psospadataready.html

Details the arguments passed to the psospaDataReady callback function by the driver.

```APIDOC
## Arguments

*   **handle**: The device identifier returned by psospaOpenUnit().
*   **status**: A PICO_STATUS code returned by the driver.
*   **noOfSamples**: The number of samples collected.
*   **overflow**: A set of flags indicating overvoltage occurrences on channels. Bit 0 represents Channel A.
*   **pParameter**: A void pointer passed from psospaGetValuesAsync(). The callback can use this to send data back to the application.
```

--------------------------------

### psospaSetTriggerChannelConditions

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospasettriggerchannelconditions.html=

Sets up trigger conditions on the scope's inputs. The trigger is defined by one or more PICO_CONDITION structures that are then ANDed together. By calling the function multiple times, additional sets of trigger conditions can be defined which are then ORed together. This AND-OR logic allows you to create any possible Boolean function of the scope's inputs. If complex triggering is not required, use psospaSetSimpleTrigger().

```APIDOC
## psospaSetTriggerChannelConditions

### Description
Sets up trigger conditions on the scope's inputs. The trigger is defined by one or more PICO_CONDITION structures that are then ANDed together. By calling the function multiple times, additional sets of trigger conditions can be defined which are then ORed together. This AND-OR logic allows you to create any possible Boolean function of the scope's inputs. If complex triggering is not required, use psospaSetSimpleTrigger().

### Function Signature
PICO_STATUS psospaSetTriggerChannelConditions(
  int16_t handle,
  PICO_CONDITION * conditions,
  int16_t nConditions,
  PICO_ACTION action
)

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **conditions** (PICO_CONDITION *) - An array of PICO_CONDITION structures specifying the conditions that should be applied to each channel. In the simplest case, the array consists of a single element. When there is more than one element, the overall trigger condition is the logical AND of all the elements.
- **nConditions** (int16_t) - The number of elements in the conditions array. If nConditions is zero then triggering is switched off.
- **action** (PICO_ACTION) - Specifies how to apply the PICO_CONDITION array to any existing trigger conditions:
  - PICO_CLEAR_ALL: Resets any previous conditions.
  - PICO_ADD: Adds this condition to any previous conditions.
  To apply only the conditions passed in the current call, specify both PICO_CLEAR_ALL | PICO_ADD together.

### Returns
- PICO_OK: Success.
- PICO_NO_TRIGGER_CONDITIONS_SET: Returned when no trigger conditions are set while the action is PICO_ADD.
- PICO_INVALID_ACTION: Returned when the action contains invalid flags.
- PICO_CLEAR_DATA_BUFFER_INVALID: Returned when the action contains invalid buffer clear flags.
- PICO_INVALID_CHANNEL: Returned when a specified channel is invalid.
- PICO_INVALID_TRIGGER_STATES: Returned when a specified trigger state is invalid.
- PICO_DUPLICATE_CONDITION_SOURCE: Returned when a duplicate condition source is detected.
```

--------------------------------

### Configure Device for Rapid Block Mode

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?rapidblockmodeexample1.html=

Sets the number of captures and configures the device for rapid block mode acquisition. Ensure the number of memory segments is sufficient for the required captures.

```c
#define MAX_WAVEFORMS 100
#define MAX_SAMPLES 1000

// set the number of waveforms to MAX_WAVEFORMS
psospaSetNoOfCaptures(handle, MAX_WAVEFORMS);
psospaRunBlock
(
  handle,
  0, // noOfPreTriggerSamples
  10000, // noOfPostTriggerSamples
  400, // sample interval in picoseconds
  &timeIndisposedMs,
  0, // first segment index to capture
  lpReady,
  &pParameter
);
```

--------------------------------

### psospaSigGenApply

Source: https://www.picotech.com/helpfiles/psospa-api/psospasiggenapply.html

Sets the signal generator running using parameters previously configured by other psospaSigGen... functions. This function is applicable in all modes.

```APIDOC
## psospaSigGenApply

### Description
This function sets the signal generator running using parameters previously configured by the other psospaSigGen... functions.

### Function Signature
PICO_STATUS psospaSigGenApply(
    int16_t handle,
    int16_t sigGenEnabled,
    int16_t sweepEnabled,
    int16_t triggerEnabled,
    double * frequency,
    double * stopFrequency,
    double * frequencyIncrement,
    double * dwellTime
)

### Parameters
#### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **sigGenEnabled** (int16_t) - Switches the signal generator on (1) or off (0).
- **sweepEnabled** (int16_t) - Switches sweep mode on (1) or off (0).
- **triggerEnabled** (int16_t) - Switches triggering of the signal generator on (1) or off (0).
- **frequency** (double *) - On exit, the actual achieved signal generator frequency (or start frequency in sweep mode).
- **stopFrequency** (double *) - On exit, the actual achieved signal generator frequency at the end of the sweep.
- **frequencyIncrement** (double *) - On exit, the actual achieved frequency step size in sweep mode.
- **dwellTime** (double *) - On exit, the actual achieved time in seconds between frequency steps in sweep mode.

### Returns
- **PICO_OK**
- **PICO_WARNING_AUX_OUTPUT_CONFLICT** - Indicates a conflict with the auxiliary output.
- **PICO_BUSY** - Indicates that the device is busy.
```

--------------------------------

### Setting Simple Trigger

Source: https://www.picotech.com/helpfiles/psospa-api/triggering.html

A convenience function to collectively set up basic trigger conditions.

```APIDOC
## psospaSetSimpleTrigger()

### Description
Sets up a simple trigger configuration by calling other trigger setting functions collectively.

### Method
(Not specified, likely a function call in a C-like API)

### Parameters
(Parameters depend on the underlying functions it calls, not explicitly detailed here.)
```

--------------------------------

### Set Data Buffers for Aggregation

Source: https://www.picotech.com/helpfiles/psospa-api/rapidblockmodeexample2.html

Configures data buffers for each channel to store aggregated maximum and minimum sample values. The buffer size is set to MAX_SAMPLES (1000).

```c
PICO_ACTION action = PICO_CLEAR_ALL | PICO_ADD;
for (int32_t c = PICO_CHANNEL_A; c <= PICO_CHANNEL_D; c++)
{
psospaSetDataBuffers
(
handle,
c,
bufferMax[c],
bufferMin[c]
MAX_SAMPLES,
PICO_INT16_T,
0,
PICO_RATIO_MODE_AGGREGATE,
action
);
action = PICO_ADD;
}
```

--------------------------------

### psospaBlockReady Callback Function Signature

Source: https://www.picotech.com/helpfiles/psospa-api/psospablockready.html

This callback function is part of your application. You register it with the PicoScope 3000E Series driver using psospaRunBlock() and the driver calls it back when block-mode data is ready. You can then download the data using the psospaGetValues() function.

```APIDOC
## psospaBlockReady Callback

### Description
This callback function is invoked by the PicoScope 3000E Series driver when block-mode data is ready. It allows your application to be notified and process the collected data.

### Signature
```c
typedef void (*psospaBlockReady)
(
  int16_t handle,
  PICO_STATUS status,
  PICO_POINTER pParameter
);
```

### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **status** (PICO_STATUS) - Indicates whether an error occurred during collection of the data.
- **pParameter** (PICO_POINTER) - A pointer passed from psospaRunBlock(). Your callback function can write to this location to send any data, such as a status flag, back to your application.

### Applicability
- Block mode only

### Returns
- Nothing
```

--------------------------------

### psospaSetDigitalPortOn

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospasetdigitalporton.html=

Sets up and enables a digital input port on the PicoScope device, configuring its logic threshold voltage.

```APIDOC
## psospaSetDigitalPortOn

### Description
This function switches on a digital port and sets its corresponding logic threshold voltage. It is applicable in all modes for any model with MSO channels fitted.

### Function Signature
PICO_STATUS psospaSetDigitalPortOn(int16_t handle, PICO_CHANNEL port, double logicThresholdLevelVolts)

### Parameters
#### Arguments
- **handle** (int16_t) - The device identifier returned by psospaOpenUnit().
- **port** (PICO_CHANNEL) - Identifies the digital port on the oscilloscope:
  - PICO_PORT0: channels D0–D7
  - PICO_PORT1: channels D8–D15
- **logicThresholdLevelVolts** (double) - The threshold voltage for the port in volts, used to distinguish the digital 0 and 1 states.

### Returns
- **PICO_OK**: The PicoScope is functioning correctly.
- **PICO_INVALID_DIGITAL_PORT**: The requested digital port number is out of range.
- **PICO_INVALID_PARAMETER**: The logicThresholdLevelVolts parameter is not valid.
- **PICO_NOT_SUPPORTED_BY_THIS_DEVICE**: The PicoScope does not have digital ports.

### Notes
Refer to the data sheet for the fastest sampling rates available with different combinations of analog and digital inputs. In most cases, the fastest rates will be obtained by disabling all analog channels. When all analog channels are disabled, you must also select 8-bit resolution to allow the digital inputs to operate alone.
```

--------------------------------

### psospaBlockReady Callback

Source: https://www.picotech.com/helpfiles/psospa-api/_hm_print_window.htm?psospablockready.html=

The psospaBlockReady callback function is registered with the PicoScope driver to be notified when block-mode data is ready. The driver calls this function, passing device handle, status, and a user-defined parameter pointer. The application can then use psospaGetValues() to download the data.

```APIDOC
## psospaBlockReady Callback Function

### Description
This callback function is part of your application. You register it with the PicoScope 3000E Series driver using `psospaRunBlock()` and the driver calls it back when block-mode data is ready. You can then download the data using the `psospaGetValues()` function.

### Applicability
* Block mode only

### Arguments
* **handle** (int16_t) - The device identifier returned by `psospaOpenUnit()`.
* **status** (PICO_STATUS) - Indicates whether an error occurred during collection of the data.
* **pParameter** (PICO_POINTER) - A pointer passed from `psospaRunBlock()`. Your callback function can write to this location to send any data, such as a status flag, back to your application.

### Returns
* Nothing
```
Tokens:
Raw