PicoScope 4000 Series (A API) PC Oscilloscopes Programmer's Guide ps4000apg.en r1 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide I Contents 1 Welcome ....................................................................................................................................1 2 Introduction....................................................................................................................................2 ........................................................................................................................................
II Contents 20 ps4000aGetValues........................................................................................................................................39 ........................................................................................................................................40 21 ps4000aGetValuesAsync ........................................................................................................................................41 22 ps4000aGetValuesBulk ..............
PicoScope 4000 Series (A API) Programmer's Guide III 6 Driver status ....................................................................................................................................88 codes 7 Programming ....................................................................................................................................89 examples 1C ........................................................................................................................................
PicoScope 4000 Series (A API) Programmer's Guide 1 1 Welcome The PicoScope 4000 Series of PC Oscilloscopes from Pico Technology is a range of compact, highresolution scope units designed to replace traditional bench-top oscilloscopes. This Programmer's Guide explains how to use the Application Programming Interface (API) for the PicoScope 4000 Series (A API) scopes.
2 Introduction 2 Introduction 2.1 Software licence conditions The material contained in this release is licensed, not sold. Pico Technology Limited grants a licence to the person who installs this software, subject to the conditions listed below. Access. The licensee agrees to allow access to this software only to persons who have been informed of these conditions and agree to abide by them. Usage.
PicoScope 4000 Series (A API) Programmer's Guide 2.3 2.4 3 Company details Address: Pico Technology James House Colmworth Business Park St. Neots Cambridgeshire PE19 8YP United Kingdom Phone: Fax: +44 (0) 1480 396 395 +44 (0) 1480 396 296 Email: Technical Support: Sales: support@picotech.com sales@picotech.com Web site: www.picotech.
4 2.5 Introduction Installation instructions IMPORTANT Do not connect your PicoScope 4000 Series scope device to the PC before you have installed the Pico Technology software. If you do, Windows might not recognise the scope device correctly. Procedure Follow the instructions in the Installation Guide included with your product package. Connect your PC Oscilloscope to the PC using the USB cable supplied.
PicoScope 4000 Series (A API) Programmer's Guide 3 5 Programming with the PicoScope 4000 Series (A API) The ps4000a.dll dynamic link library in your PicoScope installation directory allows you to program a PicoScope 4000 Series oscilloscope using standard C function calls. A typical program for capturing data consists of the following steps: Open the scope unit. Set up the input channels with the required voltage ranges and coupling mode. Set up triggering. Start capturing data.
6 3.3 Programming with the PicoScope 4000 Series (A API) Channel selection You can switch each channel on and off, and set its coupling mode to either AC or DC, using the ps4000aSetChannel function. DC coupling: AC coupling: 3.4 The scope accepts all input frequencies from zero (DC) up to its maximum analog bandwidth. The scope accepts input frequencies from a few hertz up to its maximum analog bandwidth. The lower –3 dB cutoff frequency is about 1 hertz.
PicoScope 4000 Series (A API) Programmer's Guide 3.5 7 Downsampling The driver can optionally apply a data reduction, or downsampling, process before returning data to the application. Downsampling is done by firmware on the device and is generally faster than using the PC's own processor(s). You instruct the driver to downsample by passing a downSampleRatioMode argument to one of the dataretrieval functions such as ps4000aGetValues.
8 3.6 Programming with the PicoScope 4000 Series (A API) Sampling modes PicoScope 4000 Series PC Oscilloscopes can run in various sampling modes. Block mode. In this mode, the scope stores data in internal RAM and then transfers it to the PC. When the data has been collected it is possible to examine the data, with an optional downsampling factor. The data is lost when a new run is started in the same segment, the settings are changed, or the scope is powered down. Rapid block mode.
PicoScope 4000 Series (A API) Programmer's Guide 9 Downsampling. When the data has been collected, you can set an optional downsampling factor and examine the data. Downsampling is the process of reducing the amount of data by combining adjacent samples using one of several algorithms. It is useful for zooming in and out of the data without having to repeatedly transfer the entire contents of the scope's buffer to the PC. Memory segmentation.
10 3.6.2 Programming with the PicoScope 4000 Series (A API) Rapid block mode In normal block mode, the PicoScope 4000 Series scopes collect one waveform at a time. You start the the device running, wait until all samples are collected by the device, and then download the data to the PC or start another run. There is a time overhead of tens of milliseconds associated with starting a run, causing a gap between waveforms.
PicoScope 4000 Series (A API) Programmer's Guide 3.6.2.2 11 Rapid block mode example 1: no downsampling #define MAX_SAMPLES 1000 Set up the device up as usual.
12 Programming with the PicoScope 4000 Series (A API) ps4000aGetValuesBulk ( handle, &noOfSamples, // the function 10, // 19, // 1, // PS4000A_RATIO_MODE_NONE,..// overflow // integers ) set to MAX_SAMPLES on entering fromSegmentIndex toSegmentIndex downSampleRatio downSampleRatioMode an array of size 10 int16_t Comments: the number of samples could be up to noOfPreTriggerSamples + noOfPostTriggerSamples, the values set in ps4000aRunBlock.
PicoScope 4000 Series (A API) Programmer's Guide 3.6.2.3 13 Rapid block mode example 2: using downsampling #define MAX_SAMPLES 1000 Set up the device up as usual.
14 Programming with the PicoScope 4000 Series (A API) overflow ); ps4000aGetTriggerTimeOffset64 ( handle, &time, &timeUnits, index ) } Comments: each waveform is retrieved one at a time from the driver with an aggregation of 1000. ps4000apg.en r1 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide 3.6.3 15 Streaming mode Streaming mode can capture data without the gaps that occur between blocks when using block mode. It can transfer data to the PC at speeds of up to 160 MS/s, depending on the computer's performance. This makes it suitable for high-speed data acquisition, allowing you to capture long data sets limited only by the computer's memory. Downsampling. The driver returns downsampled readings while the device is streaming.
16 3.6.4 Programming with the PicoScope 4000 Series (A API) Retrieving stored data You can collect data from the PicoScope 4000 driver with a different downsampling factor when ps4000aRunBlock or ps4000aRunStreaming has already been called and has successfully captured all the data. Use ps4000aGetValuesAsync. ps4000apg.en r1 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide 3.7 17 Timebases The API allows you to select one of 232 different timebases created by dividing the oscilloscope's master sampling clock. 3.8 Timebase (n) Sampling interval (tS) Sampling frequency (fS) n 0 1 232–1 12.5 ns × (n+1) 12.5 ns 25 ns ~54 s 80 MHz / (n+1) 80 MHz 40 MHz ~18.
18 4 API functions API functions The PicoScope 4000 Series API exports the following functions for you to use in your own applications. All functions are C functions using the standard call naming convention (__stdcall). They are all exported with both decorated and undecorated names.
PicoScope 4000 Series (A API) Programmer's Guide 19 ps4000aMinimumValue Get minimum allowed sample value ps4000aMemorySegments Divide scope memory into segments ps4000aNoOfStreamingValues Get number of samples in streaming mode ps4000aOpenUnit Open a scope device ps4000aOpenUnitAsync Open a scope device without waiting ps4000aOpenUnitProgress Check progress of OpenUnit call ps4000aRunBlock Start block mode ps4000aRunStreaming Start streaming mode ps4000aSetBandwidthFilter Enable the bandwidth limiter ps40
20 4.1 API functions ps4000aBlockReady typedef void (CALLBACK *ps4000aBlockReady) ( int16_t handle, PICO_STATUS status, void * pParameter ) This callback function is part of your application. You register it with the PicoScope 4000 Series driver using ps4000aRunBlock, and the driver calls it back when blockmode data is ready. You can then download the data using the ps4000aGetValues function. Applicability Block mode only Arguments handle, the handle of the device returning the samples.
PicoScope 4000 Series (A API) Programmer's Guide 4.2 21 ps4000aChangePowerSource PICO_STATUS ps4000aChangePowerSource ( int16_t handle, PICO_STATUS powerstate ) This function controls the two-stage power-up sequence when the device is plugged into a non-USB 3.0 port.
22 4.3 API functions ps4000aCurrentPowerSource PICO_STATUS ps4000aCurrentPowerSource ( int16_t handle ) This function returns the current power state of the device. There is no need to call this function with the PicoScope 4824 as the device has only one possible state. Applicability Reserved for future use Arguments handle, the handle of the device PICO_OK Returns ps4000apg.en r1 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide 4.4 23 ps4000aCloseUnit PICO_STATUS ps4000aCloseUnit ( int16_t handle ) This function shuts down a PicoScope 4000 scope device. Applicability All modes Arguments handle, the handle, returned by ps4000aOpenUnit, of the scope device to be closed. Returns PICO_OK PICO_HANDLE_INVALID Copyright © 2008-2014 Pico Technology Ltd. All rights reserved. ps4000apg.
24 4.5 API functions ps4000aDataReady typedef void (CALLBACK *ps4000aDataReady) ( int16_t handle, PICO_STATUS status, uint32_t noOfSamples, int16_t overflow, void * pParameter ) This function handles post-collection data returned by the driver after a call to ps4000aGetValuesAsync. It is a callback function that is part of your application. You register it with the PicoScope 4000 Series driver using ps4000aGetValuesAsync, and the driver calls it back when the data is ready.
PicoScope 4000 Series (A API) Programmer's Guide 4.6 25 ps4000aEnumerateUnits PICO_STATUS ( int16_t * int8_t * int16_t * ) ps4000aEnumerateUnits count, serials, serialLth This function counts the number of PicoScope 4000 units connected to the computer, and returns a list of serial numbers as a string. Applicability All modes Arguments * count, on exit, the number of scopes found * serials, on exit, a list of serial numbers separated by commas and terminated by a final null.
26 4.7 API functions ps4000aFlashLed PICO_STATUS ps4000aFlashLed ( int16_t handle, int16_t start ) This function flashes the LED on the front of the scope without blocking the calling thread. Calls to ps4000aRunStreaming and ps4000aRunBlock cancel any flashing started by this function. Applicability All modes Arguments handle, the handle of the scope device start, the action required: <0 0 >0 Returns ps4000apg.en r1 : flash the LED indefinitely. : stop the LED flashing. : flash the LED start times.
PicoScope 4000 Series (A API) Programmer's Guide 4.8 27 ps4000aGetAnalogueOffset PICO_STATUS ps4000aGetAnalogueOffset ( int16_t handle, PS4000A_RANGE, range, PS4000A_COUPLING coupling, float * maximumVoltage, float * minimumVoltage ) This function is used to get the maximum and minimum allowable analog offset for a specific voltage range.
28 4.9 API functions ps4000aGetChannelInformation PICO_STATUS ps4000aGetChannelInformation ( int16_t handle, PS4000A_CHANNEL_INFO info, int32_t probe, int32_t * ranges, int32_t * length, int32_t channel ) This function queries which extra ranges are available on a scope device. Applicability Reserved for future expansion Arguments handle, the handle of the required device info, the type of information required.
PicoScope 4000 Series (A API) Programmer's Guide 4.10 29 ps4000aGetMaxDownSampleRatio PICO_STATUS ps4000aGetMaxDownSampleRatio ( int16_t handle, uint32_t noOfUnaggregatedSamples, uint32_t * maxDownSampleRatio, PS4000A_RATIO_MODE downSampleRatioMode, uint32_t segmentIndex ) This function returns the maximum downsampling ratio that can be used for a given number of samples.
30 4.11 API functions ps4000aGetMaxSegments PICO_STATUS ps4000aGetMaxSegments ( int16_t handle, uint32_t * maxSegments ) This function retrieves the maximum number of memory segments allowed by the device. Applicability All modes Arguments handle, the handle of the required device * maxSegments, on exit, the maximum number of segments: PicoScope 4824: 125 000 Returns ps4000apg.en r1 PICO_OK Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide 4.12 31 ps4000aGetNoOfCaptures PICO_STATUS ps4000aGetNoOfCaptures ( int16_t handle, uint32_t * nCaptures ) This function gets the number of captures collected in one run of rapid block mode. Applicability Rapid block mode Arguments handle, the handle of the device Returns * nCaptures, on exit, the number of waveforms captured PICO_OK PICO_INVALID_HANDLE PICO_INVALID_PARAMETER Copyright © 2008-2014 Pico Technology Ltd. All rights reserved. ps4000apg.
32 4.13 API functions ps4000aGetNoOfProcessedCaptures PICO_STATUS ps4000aGetNoOfProcessedCaptures ( int16_t handle, uint32_t * nCaptures ) This function gets the number of captures collected and processed in one run of rapid block mode. Applicability Rapid block mode Arguments handle, the handle of the device * nCaptures, on exit, the number of waveforms captured and processed Returns ps4000apg.en r1 PICO_OK PICO_INVALID_HANDLE PICO_INVALID_PARAMETER Copyright © 2008-2014 Pico Technology Ltd.
PicoScope 4000 Series (A API) Programmer's Guide 4.14 33 ps4000aGetStreamingLatestValues PICO_STATUS ps4000aGetStreamingLatestValues ( int16_t handle, ps4000aStreamingReady lpPs4000Ready, void * pParameter ) This function is used to collect the next block of values while streaming is running. You must call ps4000aRunStreaming beforehand to set up streaming. Applicability Streaming mode only Arguments handle, the handle of the required device.
34 4.15 API functions ps4000aGetTimebase PICO_STATUS ps4000aGetTimebase ( int16_t handle, uint32_t timebase, int32_t noSamples, int32_t * timeIntervalNanoseconds, int32_t * maxSamples uint32_t segmentIndex ) This function discovers which timebases are available on the oscilloscope. You should set up the channels using ps4000aSetChannel first. Applicability All modes Arguments handle, the handle of the required device.
PicoScope 4000 Series (A API) Programmer's Guide 4.16 35 ps4000aGetTimebase2 PICO_STATUS ps4000aGetTimebase2 ( int16_t handle, uint32_t timebase, int32_t noSamples, float * timeIntervalNanoseconds, int32_t * maxSamples, uint32_t segmentIndex ) This function differs from ps4000aGetTimebase only in the type of the timeIntervalNanoseconds argument. Applicability All modes Arguments * timeIntervalNanoseconds, on exit, the time interval between readings at the selected timebase.
36 4.17 API functions ps4000aGetTriggerTimeOffset PICO_STATUS ps4000aGetTriggerTimeOffset ( int16_t handle, uint32_t * timeUpper, uint32_t * timeLower, PS4000A_TIME_UNITS * timeUnits, uint32_t segmentIndex ) 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.
PicoScope 4000 Series (A API) Programmer's Guide 4.18 37 ps4000aGetTriggerTimeOffset64 PICO_STATUS ps4000aGetTriggerTimeOffset64 ( int16_t handle, int64_t * time, PS4000A_TIME_UNITS * timeUnits, uint32_t segmentIndex ) This function gets the time, as a single 8-byte 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.
38 4.19 API functions ps4000aGetUnitInfo PICO_STATUS ps4000aGetUnitInfo ( int16_t handle, int8_t * string, int16_t stringLength, int16_t * requiredSize, PICO_INFO info ) This function writes information about the specified scope device to a character string. If the device fails to open, only the driver version and error code are available to explain why the last open unit call failed. Applicability All modes Arguments handle, the handle of the device from which information is required.
PicoScope 4000 Series (A API) Programmer's Guide 4.20 39 ps4000aGetValues PICO_STATUS ps4000aGetValues ( int16_t handle, uint32_t startIndex, uint32_t * noOfSamples, uint32_t downSampleRatio, PS4000A_RATIO_MODE downSampleRatioMode, uint32_t segmentIndex, int16_t * overflow ) This function returns block-mode 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.
40 4.21 API functions ps4000aGetValuesAsync PICO_STATUS ps4000aGetValuesAsync ( int16_t handle, uint32_t startIndex, uint32_t noOfSamples, uint32_t downSampleRatio, PS4000A_RATIO_MODE downSampleRatioMode, uint32_t segmentIndex, void * lpDataReady, void * pParameter ) This function returns streaming 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. It returns the data using a callback.
PicoScope 4000 Series (A API) Programmer's Guide 4.22 41 ps4000aGetValuesBulk PICO_STATUS ps4000aGetValuesBulk ( int16_t handle, uint32_t * noOfSamples, uint32_t fromSegmentIndex, uint32_t toSegmentIndex, unit32_t downSampleRatio, PS4000A_RATIO_MODE downSampleRatioMode, int16_t * overflow ) This function allows more than one waveform to be retrieved at a time in rapid block mode. The waveforms must have been collected sequentially and in the same run.
42 4.23 API functions ps4000aGetValuesOverlapped PICO_STATUS ps4000aGetValuesOverlapped ( int16_t handle, uint32_t startIndex, uint32_t * noOfSamples, uint32_t downSampleRatio, PS4000A_RATIO_MODE downSampleRatioMode, uint32_t segmentIndex, int16_t * overflow ) This function allows you to make a deferred data-collection request, which will later be executed, and the arguments validated, when you call ps4000aRunBlock in block mode.
PicoScope 4000 Series (A API) Programmer's Guide 4.
44 4.25 API functions ps4000aIsLedFlashing PICO_STATUS ps4000aIsLedFlashing ( int16_t handle, int16_t * status ) This function reports whether or not the LED is flashing. Applicability All modes Arguments handle, the handle of the scope device status, returns a flag indicating the status of the LED: <> 0 : flashing 0 : not flashing Returns ps4000apg.en r1 PICO_OK PICO_HANDLE_INVALID PICO_NULL_PARAMETER Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide 4.26 45 ps4000aIsReady PICO_STATUS ps4000aIsReady ( int16_t handle, int16_t * ready ) This function may be used instead of a callback function to receive data from ps4000aRunBlock. To use this method, pass a NULL pointer as the lpReady argument to ps4000aRunBlock. You must then poll the driver to see if it has finished collecting the requested samples.
46 4.27 API functions ps4000aIsTriggerOrPulseWidthQualifierEnabled PICO_STATUS ( int16_t int16_t * int16_t * ) ps4000aIsTriggerOrPulseWidthQualifierEnabled handle, triggerEnabled, pulseWidthQualifierEnabled This function discovers whether a trigger, or pulse width triggering, is enabled. Applicability Call after setting up the trigger, and just before calling either ps4000aRunBlock or ps4000aRunStreaming.
PicoScope 4000 Series (A API) Programmer's Guide 4.28 47 ps4000aMaximumValue PICO_STATUS ps4000aMaximumValue ( int16_t handle, int16_t * value ) This function returns the maximum possible sample value in the current operating mode. Applicability All modes Arguments handle, the handle of the required device Returns * value, on exit, the maximum value PICO_OK Copyright © 2008-2014 Pico Technology Ltd. All rights reserved. ps4000apg.
48 4.29 API functions ps4000aMinimumValue PICO_STATUS ps4000aMinimumValue ( int16_t handle, int16_t * value ) This function returns the minimum possible sample value in the current operating mode. Applicability All modes Arguments handle, the handle of the required device Returns * value, on exit, the minimum value PICO_OK ps4000apg.en r1 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide 4.30 49 ps4000aMemorySegments PICO_STATUS ps4000aMemorySegments ( int16_t handle, uint32_t nSegments, int32_t * nMaxSamples ) This function sets the number of memory segments that the scope device will use. By default, each capture fills the scope device's available memory. This function allows you to divide the memory into a number of segments so that the scope can store several captures sequentially.
50 4.31 API functions ps4000aNoOfStreamingValues PICO_STATUS ps4000aNoOfStreamingValues ( int16_t handle, uint32_t * noOfValues ) This function returns the available number of samples from a streaming run. Applicability Streaming mode. Call after ps4000aStop. Arguments handle, the handle of the required device Returns ps4000apg.
PicoScope 4000 Series (A API) Programmer's Guide 4.32 51 ps4000aOpenUnit PICO_STATUS ps4000aOpenUnit ( int16_t * handle, int8_t * serial ) This function opens a scope device. The maximum number of units that can be opened is determined by the operating system, the kernel driver and the PC's hardware.
52 4.33 API functions ps4000aOpenUnitAsync PICO_STATUS ps4000aOpenUnitAsync ( int16_t * status, int8_t * serial ) This function opens a scope device without blocking the calling thread. You can find out when it has finished by periodically calling ps4000aOpenUnitProgress until that function returns a non-zero value.
PicoScope 4000 Series (A API) Programmer's Guide 4.34 53 ps4000aOpenUnitProgress PICO_STATUS ( int16_t * int16_t * int16_t * ) ps4000aOpenUnitProgress handle, progressPercent, complete This function checks on the progress of ps4000aOpenUnitAsync. Applicability Use after ps4000aOpenUnitAsync Arguments * handle, on exit, the unit handle. -1 if the unit fails to open, 0 if no unit is found or a non-zero handle to the device. This handle is valid only if the function returns PICO_OK.
54 4.35 API functions ps4000aRunBlock PICO_STATUS ps4000aRunBlock ( int16_t handle, int32_t noOfPreTriggerSamples, int32_t noOfPostTriggerSamples, uint32_t timebase, int32_t * timeIndisposedMs, uint32_t segmentIndex, ps4000aBlockReady lpReady, void * pParameter ) This function starts a collection of data points (samples) in block mode. The number of samples is determined by noOfPreTriggerSamples and noOfPostTriggerSamples (see below for details).
PicoScope 4000 Series (A API) Programmer's Guide 55 Applicability Block mode, rapid block mode Arguments handle, the handle of the required device. noOfPreTriggerSamples, the number of samples to return before the trigger event. If no trigger has been set then this argument is ignored and noOfPostTriggerSamples specifies the maximum number of data points (samples) to collect. noOfPostTriggerSamples, the number of samples to be taken after a trigger event.
56 4.36 API functions ps4000aRunStreaming PICO_STATUS ps4000aRunStreaming ( int16_t handle, uint32_t * sampleInterval, PS4000A_TIME_UNITS sampleIntervalTimeUnits, uint32_t maxPreTriggerSamples, uint32_t maxPostTriggerSamples, int16_t autoStop, uint32_t downSampleRatio, PS4000A_RATIO_MODE downSampleRatioMode, uint32_t overviewBufferSize ) This function tells the oscilloscope to start collecting data in streaming mode.
PicoScope 4000 Series (A API) Programmer's Guide Applicability Streaming mode only Arguments handle, the handle of the required device. 57 * sampleInterval, on entry, the requested time interval between data points on entry; on exit, the actual time interval assigned. sampleIntervalTimeUnits, the unit of time that the sampleInterval is set to. See ps4000aGetTriggerTimeOffset for values. maxPreTriggerSamples, the maximum number of raw samples before a trigger condition for each enabled channel.
58 4.37 API functions ps4000aSetBandwidthFilter PICO_STATUS ps4000aSetBandwidthFilter ( int16_t handle, PS4000A_CHANNEL channel, PS4000A_BANDWIDTH_LIMITER bandwidth ) This function is reserved for future use. Applicability Not implemented Arguments handle, the handle of the required device channel, an enumerated type. The values are: PS4000A_CHANNEL_A ... PS4000A_CHANNEL_H bandwidth, the required cutoff frequency of the filter. Allowable values are: Returns ps4000apg.
PicoScope 4000 Series (A API) Programmer's Guide 4.38 59 ps4000aSetChannel PICO_STATUS ps4000aSetChannel ( int16_t handle, PS4000A_CHANNEL channel, int16_t enabled, PS4000A_COUPLING type, PS4000A_RANGE range, float analogOffset ) This function sets up the characteristics of the specified input channel. Applicability All modes Arguments handle, a unique identifier for the device. channel, the channel to be configured. The allowable values are: PS4000A_CHANNEL_A ...
60 4.39 API functions ps4000aSetDataBuffer PICO_STATUS ps4000aSetDataBuffer ( int16_t handle, PS4000A_CHANNEL channel, int16_t * buffer, int32_t bufferLth, uint32_t segmentIndex, PS4000A_RATIO_MODE mode ) This function registers your data buffer, for non-downsampled data, with the PicoScope 4000 driver. You need to allocate the buffer before calling this function. Applicability All modes. For downsampled data, use ps4000aSetDataBuffers instead.
PicoScope 4000 Series (A API) Programmer's Guide 4.40 61 ps4000aSetDataBuffers PICO_STATUS ps4000aSetDataBuffers ( int16_t handle, PS4000A_CHANNEL channel, int16_t * bufferMax, int16_t * bufferMin, int32_t bufferLth, uint32_t segmentIndex, PS4000A_RATIO_MODE mode ) This function registers your data buffers, for receiving downsampled data, with the PicoScope 4000 driver. You need to allocate memory for the buffers before calling this function. Applicability All sampling modes.
62 4.41 API functions ps4000aSetEts PICO_STATUS ps4000aSetEts ( int16_t handle, PS4000A_ETS_MODE mode, int16_t etsCycles, int16_t etsInterleave, int32_t * sampleTimePicoseconds ) This function is reserved for future use. Applicability Not implemented Arguments handle, the handle of the required device mode, not used ets_cycles, not used ets_interleave, not used * sampleTimePicoseconds, not used PICO_ETS_NOT_SUPPORTED Returns ps4000apg.en r1 Copyright © 2008-2014 Pico Technology Ltd.
PicoScope 4000 Series (A API) Programmer's Guide 4.42 63 ps4000aSetEtsTimeBuffer PICO_STATUS ( int16_t int64_t * int32_t ) ps4000aSetEtsTimeBuffer handle, buffer, bufferLth This is reserved for future use. Applicability Not implemented Arguments handle, the handle of the required device * buffer, not used bufferLth, not used PICO_ETS_NOT_SUPPORTED Returns Copyright © 2008-2014 Pico Technology Ltd. All rights reserved. ps4000apg.
64 4.43 API functions ps4000aSetEtsTimeBuffers PICO_STATUS ps4000aSetEtsTimeBuffers ( int16_t handle, uint32_t * timeUpper, uint32_t * timeLower, int32_t bufferLth ) This function is reserved for future use. Applicability Not implemented Arguments handle, the handle of the required device Returns * timeUpper, not used * timeLower, not used bufferLth, not used PICO_ETS_NOT_SUPPORTED ps4000apg.en r1 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide 4.44 65 ps4000aSetNoOfCaptures PICO_STATUS ps4000aSetNoOfCaptures ( int16_t handle, uint32_t nCaptures ) 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 one waveform.
66 4.45 API functions ps4000aSetPulseWidthQualifierConditions PICO_STATUS ps4000aSetPulseWidthQualifierConditions ( int16_t handle, PS4000A_CONDITION * conditions, int16_t nConditions, PS4000A_CONDITIONS_INFO info ) This function sets up the conditions for pulse width qualification, which can be used on its own for pulse width triggering or combined with window triggering to produce more complex triggers.
PicoScope 4000 Series (A API) Programmer's Guide 4.46 67 ps4000aSetPulseWidthQualifierProperties PICO_STATUS ps4000aSetPulseWidthQualifierProperties ( int16_t handle, PS4000A_THRESHOLD_DIRECTION direction, uint32_t lower, uint32_t upper, PS4000A_PULSE_WIDTH_TYPE type ) This function configures the general properties of the pulse width qualifier. Applicability All modes Arguments handle, the handle of the required device direction, the direction of the signal required for the trigger to fire.
68 4.
PicoScope 4000 Series (A API) Programmer's Guide 69 It is also possible to sweep the frequency by continually modifying the deltaPhase. This is done by setting up a deltaPhaseIncrement that the oscilloscope adds to the deltaPhase at specified intervals.
70 API functions indexMode, specifies how the signal will be formed from the arbitrary waveform data. SINGLE, DUAL and QUAD index modes are possible (see AWG index modes). shots, the number of cycles of the waveform to be produced after a trigger event. If this is set to a non-zero value [1, MAX_SWEEPS_SHOTS], then sweeps must be set to zero. sweeps, the number of times to sweep the frequency after a trigger event, according to sweepType.
PicoScope 4000 Series (A API) Programmer's Guide 71 4.47.1 AWG index modes The arbitrary waveform generator supports SINGLE, DUAL and QUAD index modes to make the best use of the waveform buffer. SINGLE mode. The generator outputs the raw contents of the buffer repeatedly. This mode is the only one that can generate asymmetrical waveforms. You can also use this mode for symmetrical waveforms, but the dual and quad modes make more efficient use of the buffer memory. DUAL mode.
72 4.
PicoScope 4000 Series (A API) Programmer's Guide 73 stopFrequency, the frequency in hertz at which the sweep should reverse direction or return to the start frequency. Range: MIN_SIG_GEN_FREQ to MAX_SIG_GEN_FREQ. increment, the amount in hertz by which the frequency rises or falls every dwellTime seconds in sweep mode. dwellTime, the time in seconds between frequency changes in sweep mode.
74 4.49 API functions ps4000aSetSigGenPropertiesArbitrary PICO_STATUS ps4000aSetSigGenPropertiesArbitrary ( int16_t handle, uint32_t startDeltaPhase, uint32_t stopDeltaPhase, uint32_t deltaPhaseIncrement, uint32_t dwellCount, PS4000A_SWEEP_TYPE sweepType, uint32_t shots, uint32_t sweeps, PS4000A_SIGGEN_TRIG_TYPE triggerType, PS4000A_SIGGEN_TRIG_SOURCE triggerSource, int16_t extInThreshold ) This function reprograms the arbitrary waveform generator.
PicoScope 4000 Series (A API) Programmer's Guide 4.50 75 ps4000aSetSigGenPropertiesBuiltIn PICO_STATUS ps4000aSetSigGenPropertiesBuiltIn ( int16_t handle, double startFrequency, double stopFrequency, double increment, double dwellTime, PS4000A_SWEEP_TYPE sweepType, uint32_t shots, uint32_t sweeps, PS4000A_SIGGEN_TRIG_TYPE triggerType, PS4000A_SIGGEN_TRIG_SOURCE triggerSource, int16_t extInThreshold ) This function reprograms the signal generator.
76 4.51 API functions ps4000aSetSimpleTrigger PICO_STATUS ps4000aSetSimpleTrigger ( int16_t handle, int16_t enable, PS4000A_CHANNEL source, int16_t threshold, PS4000A_THRESHOLD_DIRECTION direction, uint32_t delay, int16_t autoTrigger_ms ) 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.
PicoScope 4000 Series (A API) Programmer's Guide 4.52 77 ps4000aSetTriggerChannelConditions PICO_STATUS ps4000aSetTriggerChannelConditions ( int16_t handle, PS4000A_CONDITION * conditions, int16_t nConditions, PS4000A_CONDITIONS_INFO info ) This function sets up trigger conditions on the scope's inputs. The trigger is set up by defining an array of one or more PS4000A_CONDITION structures that are then ANDed together.
78 API functions 4.52.
PicoScope 4000 Series (A API) Programmer's Guide 4.53 79 ps4000aSetTriggerChannelDirections PICO_STATUS ps4000aSetTriggerChannelDirections ( int16_t handle, PS4000A_DIRECTION * directions, int16_t nDirections ) This function sets the direction of the trigger for the specified channels. Applicability All modes. Arguments handle, the handle of the required device. * directions, on entry, an array of structures containing trigger directions. See PS4000A_DIRECTION for allowable values.
80 API functions 4.53.1 PS4000A_DIRECTION structure A structure of this type is passed to ps4000aSetTriggerChannelDirections in the directions argument to specify the trigger direction for a specified source, and is defined as follows: - typedef struct tPS4000ADirection { PS4000A_CHANNEL channel; PS4000A_THRESHOLD_DIRECTION direction; } PS4000A_DIRECTION; Each structure is the logical AND of the states of the scope's inputs.
PicoScope 4000 Series (A API) Programmer's Guide 4.54 81 ps4000aSetTriggerChannelProperties PICO_STATUS ps4000aSetTriggerChannelProperties ( int16_t handle, PS4000A_TRIGGER_CHANNEL_PROPERTIES * channelProperties, int16_t nChannelProperties, int16_t auxOutputEnable, int32_t autoTriggerMilliseconds ) This function is used to enable or disable triggering and set its parameters. Applicability All modes Arguments handle, the handle of the required device.
82 API functions 4.54.
PicoScope 4000 Series (A API) Programmer's Guide 4.55 83 ps4000aSetTriggerDelay PICO_STATUS ps4000aSetTriggerDelay ( int16_t handle, uint32_t delay ) This function sets the post-trigger delay, which causes capture to start a defined time after the trigger event. Applicability All modes Arguments handle, the handle of the required device delay, the time between the trigger occurring and the first sample, in sample periods.
84 4.56 API functions ps4000aSigGenSoftwareControl PICO_STATUS ps4000aSigGenSoftwareControl ( int16_t handle, int16_t state ) This function causes a trigger event, or starts and stops gating. It is used when the signal generator is set to SIGGEN_SOFT_TRIG . Applicability Use with ps4000aSetSigGenBuiltIn or ps4000aSetSigGenArbitrary. Arguments handle, the handle of the required device state, sets the trigger gate high or low when the trigger type is set to either SIGGEN_GATE_HIGH or SIGGEN_GATE_LOW.
PicoScope 4000 Series (A API) Programmer's Guide 4.57 85 ps4000aStop PICO_STATUS ps4000aStop ( int16_t handle ) This function stops the scope device from sampling data. If this function is called before a trigger event occurs, the oscilloscope may not contain valid data. Always call this function after the end of a capture to ensure that the scope is ready for the next capture. Applicability All modes Arguments handle, the handle of the required device.
86 4.58 API functions ps4000aStreamingReady typedef void ( int16_t int32_t uint32_t int16_t uint32_t int16_t int16_t void * ) (CALLBACK *ps4000aStreamingReady) handle, noOfSamples, startIndex, overflow, triggerAt, triggered, autoStop, pParameter This callback function is part of your application. You register it with the PicoScope 4000 Series driver using ps4000aGetStreamingLatestValues, and the driver calls it back when streaming-mode data is ready.
PicoScope 4000 Series (A API) Programmer's Guide 5 87 Enumerated types and constants Enumerated types and constants are defined in the file ps4000aApi.h, which is included in the SDK. We recommend that you refer to these constants by name unless your programming environment understands only numeric values. Copyright © 2008-2014 Pico Technology Ltd. All rights reserved. ps4000apg.
88 6 Driver status codes Driver status codes Every function in the ps4000a.dll driver returns a status code from the list of PICO_STATUS values defined in the picoStatus.h header file supplied with the SDK. See the header file for more information. ps4000apg.en r1 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
PicoScope 4000 Series (A API) Programmer's Guide 7 89 Programming examples The SDK includes programming examples for a number of languages and development environments. 7.1 C The SDK includes a console-mode program (ps4000acon.c) that demonstrates how to use the PicoScope 4000 driver in Windows.
90 Programming examples PicoErrorHandler.vi - takes an error cluster and, if an error has occurred, displays a message box indicating the source of the error and the status code returned by the driver PicoScope4000aAdvancedTriggerSettings.vi - an interface for the advanced trigger features of the oscilloscope This VI is not required for setting up simple triggers, which are configured using PicoScope4000aSettings.vi.
PicoScope 4000 Series (A API) Programmer's Guide 91 PicoScope4000aGetStreamingValues.vi - used in streaming mode to get the latest values from the driver This VI should be called in a loop after the oscilloscope has been set up using PicoScope4000aSettings.vi and streaming has been started by calling PicoScope4000aStartStreaming.vi. The VI outputs the number of samples available and the start index of these samples in the array output by PicoScope4000aStartStreaming.vi. PicoScope4000aOpen.
92 8 Glossary Glossary AC/DC switch. To switch from AC coupling to DC coupling, or vice versa, select AC or DC from the control on the PicoScope toolbar. The AC setting filters out very lowfrequency components of the input signal, including DC, and is suitable for viewing small AC signals superimposed on a DC or slowly changing offset. In this mode you can measure the peak-to-peak amplitude of an AC signal but not its absolute value. Use the DC setting for measuring the absolute value of a signal. ADC.
PicoScope 4000 Series (A API) Programmer's Guide 93 PC Oscilloscope. A virtual instrument formed by connecting a PicoScope 4000 Series scope unit to a computer running the PicoScope software. PicoScope 4000 Series. A range of high-resolution PC Oscilloscopes from Pico Technology. The range includes two-channel and four-channel models, with or without a built-in function generator and arbitrary waveform generator. PicoScope software. A software product that accompanies all Pico PC Oscilloscopes.
PicoScope 4000 Series (A API) Programmer's Guide Index 95 Excel 89 F A Filter, bandwidth-limiting Function calls AC/DC coupling setting 59 6 18 Functions ps4000aBlockReady 20 ps4000aChangePowerSource Aggregation 7, 15 getting ratio 29 ps4000aCloseUnit Analog offset 27 API function calls 18 Arbitrary waveform generator index modes 71 AWG 68 AWG index modes 58 68 ps4000aCurrentPowerSource 22 ps4000aDataReady 24 ps4000aEnumerateUnits 25 ps4000aFlashLed 26 ps4000aGetAnalogueOffset 27 ps4000aGet
96 Index Functions ps4000aSetPulseWidthQualifierConditions 66 ps4000aSetPulseWidthQualifierProperties 67 ps4000aSetSigGenArbitrary 68 ps4000aSetSigGenBuiltIn 72 ps4000aSetSigGenPropertiesArbitrary ps4000aSetSigGenPropertiesBuiltIn 74 75 Excel 89 LabVIEW 89 PS4000A_CHANNEL constants 59 PS4000A_CONDITION structure PS4000A_DIRECTION structure PS4000A_LEVEL 82 PS4000A_LOST_DATA 78 80 5 ps4000aSetSimpleTrigger 76 ps4000aSetTriggerChannelConditions ps4000aSetTriggerChannelDirections 77 79 PS4000A_M
PicoScope 4000 Series (A API) Programmer's Guide 97 T Technical support Threshold voltage 3 6 Timebase 17 setting 34, 35 Trademarks 2 Trigger 6 conditions 77 delay 83 directions 79, 80 pulse width qualifier 46, 66, 67 pulse width qualifier conditions 78 setting up 76 time offset 36, 37 U USB 3 changing ports hub 4 17 V Voltage ranges 5 W Windows, Microsoft 3 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved. ps4000apg.
PicoScope 4000 Series (A API) Programmer's Guide Copyright © 2008-2014 Pico Technology Ltd. All rights reserved. 99 ps4000apg.
Pico Technology James House Colmworth Business Park ST. NEOTS Cambridgeshire PE19 8YP United Kingdom Tel: +44 (0) 1480 396 395 Fax: +44 (0) 1480 396 296 www.picotech.com ps4000apg.en r1 2014-02-17 Copyright © 2008-2014 Pico Technology Ltd. All rights reserved.
