Pico Picoscope 5000 series Manual

Programmer's Guide

ps5000apg.en r2

PicoScope 5000 Series (A API)

PC Oscilloscopes

IPicoScope 5000 Series (A API) Programmer's Guide

Contents

....................................................................................................................................11 Introduction

........................................................................................................................................1

1 Overview

........................................................................................................................................2

2 Minimum PC requirements

........................................................................................................................................3

3 License agreement

....................................................................................................................................42 Programming the 5000 Series oscilloscopes

....................................................................................................................................53 The ps5000a driver

....................................................................................................................................64 System requirements

....................................................................................................................................75 Voltage ranges

....................................................................................................................................86 Triggering

....................................................................................................................................97 Sampling modes

........................................................................................................................................10

1 Block mode

......................................................................................................................................................................11

1 Using block mode

......................................................................................................................................................................11

2 Asynchronous calls in block mode

........................................................................................................................................12

2 Rapid block mode

......................................................................................................................................................................12

1 Using rapid block mode

......................................................................................................................................................................14

2 Rapid block mode example 1: no aggregation

......................................................................................................................................................................16

3 Rapid block mode example 2: using aggregation

........................................................................................................................................17

3 ETS (Equivalent Time Sampling)

......................................................................................................................................................................18

1 Using ETS mode

........................................................................................................................................19

4 Streaming mode

......................................................................................................................................................................19

1 Using streaming mode

........................................................................................................................................20

5 Retrieving stored data

....................................................................................................................................218 Timebases

....................................................................................................................................229 Power options

....................................................................................................................................2310 Combining several oscilloscopes

....................................................................................................................................2411 API functions

........................................................................................................................................26

1 ps5000aBlockReady (callback)

........................................................................................................................................27

2 ps5000aChangePowerSource

........................................................................................................................................28

3 ps5000aCloseUnit

........................................................................................................................................29

4 ps5000aCurrentPowerSource

........................................................................................................................................30

5 ps5000aDataReady (callback)

........................................................................................................................................31

6 ps5000aEnumerateUnits

........................................................................................................................................32

7 ps5000aFlashLed

........................................................................................................................................33

8 ps5000aGetAnalogueOffset

........................................................................................................................................34

9 ps5000aGetChannelInformation

........................................................................................................................................35

10 ps5000aGetDeviceResolution

ContentsII

........................................................................................................................................36

11 ps5000aGetMaxDownSampleRatio

........................................................................................................................................37

12 ps5000aGetMaxSegments

........................................................................................................................................38

13 ps5000aGetNoOfCaptures

........................................................................................................................................39

14 ps5000aGetNoOfProcessedCaptures

........................................................................................................................................40

15 ps5000aGetStreamingLatestValues

........................................................................................................................................41

16 ps5000aGetTimebase

........................................................................................................................................42

17 ps5000aGetTimebase2

........................................................................................................................................43

18 ps5000aGetTriggerTimeOffset

........................................................................................................................................44

19 ps5000aGetTriggerTimeOffset64

........................................................................................................................................45

20 ps5000aGetUnitInfo

........................................................................................................................................47

21 ps5000aGetValues

......................................................................................................................................................................48

1 Downsampling modes

........................................................................................................................................49

22 ps5000aGetValuesAsync

........................................................................................................................................50

23 ps5000aGetValuesBulk

........................................................................................................................................51

24 ps5000aGetValuesOverlapped

........................................................................................................................................52

25 ps5000aGetValuesOverlappedBulk

........................................................................................................................................53

26 ps5000aGetValuesTriggerTimeOffsetBulk

........................................................................................................................................55

27 ps5000aGetValuesTriggerTimeOffsetBulk64

........................................................................................................................................56

28 ps5000aIsReady

........................................................................................................................................57

29 ps5000aIsTriggerOrPulseWidthQualifierEnabled

........................................................................................................................................58

30 ps5000aMaximumValue

........................................................................................................................................59

31 ps5000aMemorySegments

........................................................................................................................................60

32 ps5000aMinimumValue

........................................................................................................................................61

33 ps5000aNoOfStreamingValues

........................................................................................................................................62

34 ps5000aOpenUnit

........................................................................................................................................63

35 ps5000aOpenUnitAsync

........................................................................................................................................64

36 ps5000aOpenUnitProgress

........................................................................................................................................65

37 ps5000aPingUnit

........................................................................................................................................66

38 ps5000aRunBlock

........................................................................................................................................68

39 ps5000aRunStreaming

........................................................................................................................................70

40 ps5000aSetBandwidthFilter

........................................................................................................................................71

41 ps5000aSetChannel

........................................................................................................................................73

42 ps5000aSetDataBuffer

........................................................................................................................................74

43 ps5000aSetDataBuffers

........................................................................................................................................75

44 ps5000aSetDeviceResolution

........................................................................................................................................76

45 ps5000aSetEts

........................................................................................................................................77

46 ps5000aSetEtsTimeBuffer

........................................................................................................................................78

47 ps5000aSetEtsTimeBuffers

........................................................................................................................................79

48 ps5000aSetNoOfCaptures

........................................................................................................................................80

49 ps5000aSetPulseWidthQualifier

......................................................................................................................................................................82

1 ps5000a_PWQ_CONDITIONS structure

........................................................................................................................................83

50 ps5000aSetSigGenArbitrary

......................................................................................................................................................................85

1 AWG index modes

........................................................................................................................................87

51 ps5000aSetSigGenBuiltIn

........................................................................................................................................90

52 ps5000aSetSigGenPropertiesArbitrary

IIIPicoScope 5000 Series (A API) Programmer's Guide

........................................................................................................................................91

53 ps5000aSetSigGenPropertiesBuiltIn

........................................................................................................................................92

54 ps5000aSetSimpleTrigger

........................................................................................................................................93

55 ps5000aSetTriggerChannelConditions

......................................................................................................................................................................94

1 PS5000A_TRIGGER_CONDITIONS structure

........................................................................................................................................95

56 ps5000aSetTriggerChannelDirections

........................................................................................................................................96

57 ps5000aSetTriggerChannelProperties

......................................................................................................................................................................97

1 PS5000A_TRIGGER_CHANNEL_PROPERTIES structure

........................................................................................................................................98

58 ps5000aSetTriggerDelay

........................................................................................................................................99

59 ps5000aSigGenArbitraryMinMaxValues

........................................................................................................................................100

60 ps5000aSigGenFrequencyToPhase

........................................................................................................................................101

61 ps5000aSigGenSoftwareControl

........................................................................................................................................102

62 ps5000aStop

........................................................................................................................................103

63 ps5000aStreamingReady (callback)

....................................................................................................................................10412 Programming examples

....................................................................................................................................10513 Driver status codes

....................................................................................................................................11014 Enumerated types and constants

....................................................................................................................................11115 Numeric data types

....................................................................................................................................11216 Glossary

....................................................................................................................................115

Index

PicoScope 5000 Series (A API) Programmer's Guide 1

1 Introduction

1.1 Overview

The PicoScope 5000 A and B Series PC

Oscilloscopes from Pico Technology are a range

of high-specification, real-time measuring

instruments that connect to the USB port of

your computer. The series covers various

options of portability, deep memory, fast

sampling rates and high bandwidth, making it

a highly versatile range that suits a wide range

of applications. The oscilloscopes are all hi-

speed USB 2.0 devices, also compatible with

USB 1.1 and USB 3.0.

Ext G

PicoScope

www.picotech.com

PicoScope 5000 Series

BCD

Ext G

PicoScope

www.picotech.com

PicoScope 5000 Series

This manual explains how to use the API (application programming interface)

functions, so that you can develop your own programs to collect and analyze data from

the oscilloscope.

The information in this manual applies to the following oscilloscopes:

PicoScope 5242A

PicoScope 5243A

PicoScope 5244A

PicoScope 5442A

PicoScope 5443A

PicoScope 5444A

The A models are high speed portable

oscilloscopes, with a function generator.

PicoScope 5242B

PicoScope 5243B

PicoScope 5244B

PicoScope 5442B

PicoScope 5443B

PicoScope 5444B

The B models are as the A models, but

feature an arbitrary waveform generator

and deeper memory.

For information on any PicoScope 5000 Series oscilloscope, refer to the documentation

on our website.

Introduction2

1.2 Minimum PC requirements

To ensure that your PicoScope 5000 Series Oscilloscope operates correctly, you must

have a computer with at least the minimum system requirements as shown in the

following table. The performance of the oscilloscope will be better with a more

powerful PC, and will benefit from a multi-core processor. Please note the PicoScope

software is not installed as part of the SDK.

Item

Absolute

minimum

Recommended

minimum

Recommended

full specification

Operating system

Windows XP SP3

Windows Vista

Windows 7

Windows 8*

32 bit and 64** bit versions supported

Processor

As required

by Windows

1 GHz

Memory

512 MB

Free disk space***

32-bit: 600 MB

64-bit: 1.5 GB

32-bit: 850 MB

64-bit: 2 GB

Ports

USB 1.1 compliant port

USB 2.0 or 3.0 compliant port

* Not Windows RT.

** While the driver will run on a 64 bit operating system, the driver itself is 32 bit,

and therefore will run as a 32 bit.

*** The PicoScope software does not use all the disk space specified in the table.

The free space is required to make Windows run efficiently.

PicoScope 5000 Series (A API) Programmer's Guide 3

1.3 License agreement

Grant of license. The material contained in this release is licensed, not sold. Pico

Technology Limited ('Pico') grants a license 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 and agree to abide by these conditions.

Usage. The software in this release is for use only with Pico products or with data

collected using Pico products.

collected using Pico products. You may copy and distribute the SDK without restriction,

as long as you do not remove any Pico Technology copyright statements. The example

programs in the SDK may be modified, copied and distributed for the purpose of

developing programs to collect data using Pico products.

Liability. Pico and its agents shall not be liable for any loss or damage, howsoever

caused, related to the use of Pico equipment or software, unless excluded by statute.

Fitness for purpose. No two applications are the same, so Pico cannot guarantee

that its equipment or software is suitable for a given application. It is therefore the

user's responsibility to ensure that the product is suitable for the user's application.

Mission-critical applications. Because the software runs on a computer that may be

running other software products, and may be subject to interference from these other

products, this license specifically excludes usage in 'mission-critical' applications, for

example life-support systems.

Viruses. This software was continuously monitored for viruses during production.

However, the user is responsible for virus checking the software once it is installed.

Support. No software is ever error-free, but if you are dissatisfied with the

performance of this software, please contact our technical support staff.

Upgrades. We provide upgrades, free of charge, from our web site at

www.picotech.com. We reserve the right to charge for updates or replacements sent

out on physical media.

Trademarks. Windows is a trademark or registered trademark of Microsoft

Corporation. Pico Technology Limited and PicoScope are internationally registered

trademarks.

Programming the 5000 Series oscilloscopes4

2 Programming the 5000 Series oscilloscopes

The ps5000a.dll dynamic link library in your PicoScope installation directory allows

you to program a PicoScope 5000 Series (A API) 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 type.

Set up triggering.

Start capturing data. (See Sampling modes, where programming is discussed in

more detail.)

Wait until the scope unit is ready.

Stop capturing data.

Copy data to a buffer.

Close the scope unit.

Numerous sample programs are included in the SDK. These demonstrate how to use

the functions of the driver software in each of the modes available.

PicoScope 5000 Series (A API) Programmer's Guide 5

3 The ps5000a driver

Your application will communicate with a driver called ps5000a.dll. This driver is

used by all the 5000 A/B Series oscilloscopes (but not the PicoScope 5203 and 5204).

The driver exports the PicoScope 5000 function definitions in standard C format, but

this does not limit you to programming in C: you can use the API with any

programming language that supports standard C calls.

The API driver depends on another DLL, PicoIpp.dll, and a low-level driver,

WinUsb.sys. These are installed by the SDK when you plug the oscilloscope into the

computer for the first time. Your application does not call these drivers directly.

System requirements6

4 System requirements

General requirements

See Minimum PC requirements.

USB

The PicoScope 5000A driver offers four different methods of recording data, all of

which support both USB 1.1, USB 2.0, and USB 3.0 connections. The 5000 A and B

Series oscilloscopes are all hi-speed USB 2.0 devices, so transfer rate will not increase

by using USB 3.0, but it will decrease when using USB 1.1.

PicoScope 5000 Series (A API) Programmer's Guide 7

5 Voltage ranges

You can set a device input channel to any voltage range from ±10 mV to ±20 V with

the ps5000aSetChannel function. Each sample is scaled to 16 bits so that the values

returned to your application are as follows:

Function

Voltage

Value returned

decimal

hex

8-bit

ps5000aMinimumValue

minimum

–32 512

8100

zero

0000

ps5000aMaximumValue

maximum

+32 512

7F00

12, 14, 15 and 16-bit

ps5000aMinimumValue

minimum

–32 767

8001

zero

0000

ps5000aMaximumValue

maximum

+32 767

7FFF

You can determine the minimum and maximum scaled values for the currently

selected resolution using the ps5000aMinimumValue and ps5000aMaximumValue

function calls.

Triggering8

6 Triggering

PicoScope 5000 Series oscilloscopes can either start collecting data immediately, or be

programmed to wait for a trigger event to occur. In both cases you need to use the

PicoScope 5000 trigger function ps5000aSetSimpleTrigger,which in turn calls

ps5000aSetTriggerChannelConditions,

ps5000aSetTriggerChannelDirections and

ps5000aSetTriggerChannelProperties (these can also be called individually,

rather than using ps5000aSetSimpleTrigger in order to set up advanced trigger

types such as pulse width). A trigger event can occur when one of the signal or trigger

input channels crosses a threshold voltage on either a rising or a falling edge.

PicoScope 5000 Series (A API) Programmer's Guide 9

7 Sampling modes

PicoScope 5000 Series oscilloscopes can run in various sampling modes.

Block mode.In this mode, the scope stores data in its buffer memory 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.

ETS mode.In this mode, it is possible to increase the effective sampling rate of the

scope when capturing repetitive signals. It is a modified form of block mode.

Rapid block mode.This is a variant of block mode that allows you to capture more

than one waveform at a time with a minimum of delay between captures. You can

use downsampling in this mode if you wish.

Streaming mode.In this mode, data is passed directly to the PC without entire

blocks being stored in the scope's buffer memory. This enables long periods of slow

data collection for chart recorder and data-logging applications. Streaming mode

supports downsampling and triggering, while providing fast streaming at up to:

8-bit mode

7.8125 MS/s (128 ns per sample) when three or four channels are active

15.625 MS/s (64 ns per sample) when two channels are active

31.25 MS/s (32 ns per sample) when one channel is active

12, 14, 15, and 16-bit modes*

3.906 MS/s (256 ns per sample) when three or four channels are active

7.8125 MS/s (128 ns per sample) when two channels are active

15.625 MS/s (64 ns per sample) when one channel is active

* 15-bit mode supports a maximum of two channels. 16-bit mode supports only

one channel.

In all sampling modes, the driver returns data asynchronously using a callback. This is

a call to one of the functions in your own application. When you request data from the

scope, you pass to the driver a pointer to your callback function. When the driver has

written the data to your buffer, it makes a callback (calls your function) to signal that

the data is ready. The callback function then signals to the application that the data is

available.

Because the callback is called asynchronously from the rest of your application, in a

separate thread, you must ensure that it does not corrupt any global variables while it

runs.

For compatibility of programming environments not supporting callback, polling of the

driver is available in block mode.

Note: The Oversampling feature has been replaced by

PS5000A_RATIO_MODE_AVERAGE.

Sampling modes10

7.1 Block mode

In block mode, the computer prompts a PicoScope 5000 Series oscilloscope to collect

a block of data into its internal memory. When the oscilloscope has collected the whole

block, it signals that it is ready and then transfers the whole block to the computer's

memory through the USB port.

Block size. The maximum number of values depends upon the size of the

oscilloscope's memory. The memory buffer is shared between the enabled channels,

so if two channels are enabled, each receives half the memory. These features are

handled transparently by the driver. The block size also depends on the number of

memory segments in use (see ps5000aMemorySegments).

Sampling rate. A PicoScope 5000 Series oscilloscope can sample at a number of

different rates according to the selected timebase and the combination of channels

that are enabled. See the PicoScope 5000 Series User's Guide for the specifications

that apply to your scope model.

Setup time. The driver normally performs a number of setup operations, which can

take up to 50 milliseconds, before collecting each block of data. If you need to

collect data with the minimum time interval between blocks, use rapid block mode

and avoid calling setup functions between calls to ps5000aRunBlock, ps5000aStop

and ps5000aGetValues.

Downsampling. When the data has been collected, you can set an optional

downsampling factor and examine the data. Downsampling is a process that

reduces the amount of data by combining adjacent samples. 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.

Segmented memory. The scope's internal memory can be divided into segments

so that you can capture several waveforms in succession. Configure this using

ps5000aMemorySegments.

Data retention. The data is lost when a new run is started in the same segment,

the settings are changed, or the scope is powered down or the power source is

changed (for flexible power devices).

See Using block mode for programming details.

PicoScope 5000 Series (A API) Programmer's Guide 11

7.1.1 Using block mode

You can use block mode with or without aggregation. With aggregation, you need to

set up two buffers for each channel to receive the minimum and maximum values,

see rapid block mode example 1 for an example of using aggregation.

The below is the general procedure for reading and displaying data in block mode

using a single memory segment:

1. Open the oscilloscope using ps5000aOpenUnit.

2. Select channel ranges and AC/DC coupling using ps5000aSetChannel.

3. Using ps5000aGetTimebase, select timebases until the required nanoseconds per

sample is located.

4. Use the trigger setup functions ps5000aSetTriggerChannelDirections and

ps5000aSetTriggerChannelProperties to set up the trigger if required.

5. Start the oscilloscope running using ps5000aRunBlock.

6. Wait until the oscilloscope is ready using the ps5000aBlockReady callback (or

poll using ps5000aIsReady).

7. Use ps5000aSetDataBuffer to tell the driver where your memory buffer is.

8. Transfer the block of data from the oscilloscope using ps5000aGetValues.

9. Display the data.

10. Stop the oscilloscope using ps5000aStop.

11. Repeat steps 5 to 9.

12. Request new views of stored data using different downsampling parameters: see

Retrieving stored data.

7.1.2 Asynchronous calls in block mode

The ps5000aGetValues function may take a long time to complete if a large amount of

data is being collected. For example, it can take 14 seconds (or several minutes on

USB 1.1) to retrieve the full 512 Msamples (in 8-bit mode) from a PicoScope 5444B

using a USB 2.0 connection. To avoid hanging the calling thread, it is possible to call

ps5000aGetValuesAsync instead. This immediately returns control to the calling

thread, which then has the option of waiting for the data or calling ps5000aStop to

abort the operation.

Sampling modes12

7.2 Rapid block mode

In normal block mode, the PicoScope 5000 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. When you collect data from the device, there is another minimum time

overhead which is most noticeable when using a small number of samples.

Rapid block mode allows you to sample several waveforms at a time with the

minimum time between waveforms. It reduces the gap from milliseconds to less than

2 microseconds (on fastest timebase).

See Using rapid block mode for details.

7.2.1 Using rapid block mode

You can use rapid block mode with or without aggregation. With aggregation, you

need to set up two buffers for each channel to receive the minimum and maximum

values.

Without aggregation

1. Open the oscilloscope using ps5000aOpenUnit.

2. Select channel ranges and AC/DC coupling using ps5000aSetChannel.

3. Using ps5000aGetTimebase, select timebases until the required nanoseconds per

sample is located.

4. Use the trigger setup functions ps5000aSetTriggerChannelDirections and

ps5000aSetTriggerChannelProperties to set up the trigger if required.

5. Set the number of memory segments equal to or greater than the number of

captures required using ps5000aMemorySegments. Use

ps5000aSetNoOfCaptures before each run to specify the number of waveforms to

capture.

6. Start the oscilloscope running using ps5000aRunBlock.

THEN EITHER

7a. To obtain data before rapid block capture has finished, call ps5000aStop and

then ps5000aGetNoOfCaptures to find out how many captures were completed.

7b. Wait until the oscilloscope is ready using ps5000aIsReady.

7c. Wait on the callback function.

8. Use ps5000aSetDataBuffer to tell the driver where your memory buffers are.

9. Transfer the blocks of data from the oscilloscope using ps5000aGetValuesBulk

(or ps5000aGetValues to retrieve one buffer at a time). These functions stop the

oscilloscope.

10. Retrieve the time offset for each data segment using

ps5000aGetValuesTriggerTimeOffsetBulk64.

11. Display the data.

12. Repeat steps 6 to 11 if necessary.

13. Call ps5000aStop (usually unnecessary as the scope stops automatically in most

cases, but recommended as a precaution).

PicoScope 5000 Series (A API) Programmer's Guide 13

With aggregation

To use rapid block mode with aggregation, follow steps 1 to 7 above, then proceed as

follows:

8a. Call ps5000aSetDataBuffer or (ps5000aSetDataBuffers) to set up one pair of

buffers for every waveform segment required.

9a. Call ps5000aGetValuesBulk for each pair of buffers.

10a. Retrieve the time offset for each data segment using

ps5000aGetValuesTriggerTimeOffsetBulk64.

Continue from step 11 above.

Sampling modes14

7.2.2 Rapid block mode example 1: no aggregation

#define MAX_SAMPLES 1000

Set up the device up as usual.

Open the device

Channels

Trigger

Number of memory segments (this should be equal or more than the no of captures

required)

// set the number of waveforms to 100

ps5000aSetNoOfCaptures (handle, 100);

pParameter = false;

ps5000aRunBlock

(handle,

0, // noOfPreTriggerSamples

10000, // noOfPostTriggerSamples

1, // timebase to be used

&timeIndisposedMs,

1, // segment index

lpReady,

&pParameter

);

Comment: these variables have been set as an example and can be any valid value.

pParameter will be set true by your callback function lpReady.

while (!pParameter) Sleep (0);

for (int i = 0; i < 10; i++)

{for (int c = PS5000A_CHANNEL_A; c <= PS5000A_CHANNEL_B; c++)

{ps5000aSetDataBuffer

(handle,

&buffer[c][i],

MAX_SAMPLES,

PS5000A_RATIO_MODE_NONE

);

}

Comments: buffer has been created as a two-dimensional array of pointers to shorts,

which will contain 1000 samples as defined by MAX_SAMPLES. There are only 10 buffers

set, but it is possible to set up to the number of captures you have requested.

PS5000A_RATIO_MODE_NONE can be substituted for PS5000A_RATIO_MODE_AGGREGATE,

PS5000A_RATIO_MODE_DECIMATE, or PS5000A_RATIO_MODE_AVERAGE.

This manual suits for next models

Table of contents

Popular Test Equipment manuals by other brands

Tektronix

Tektronix M 581 Series instruction manual

Tektronix

Tektronix 2445 instruction manual

YOKOGAWA

YOKOGAWA CA11E user manual

Stahlwille

Stahlwille 7707-1-2W operating instructions

Argus

Argus Optical Light Source user guide

Environics

Environics 6103 user guide

TIS

TIS 600 user manual

Covita

Covita Smokerlyzer Micro+ quick start guide

Aegis

Aegis CZ20053 operating manual

Martel

Martel 19C1977 operating instructions

ATEQ

ATEQ VT47S user manual

METREL

METREL Eutrotest PB instruction manual

Gammon

Gammon Aqua-Glo III Series manual

OTC

OTC Genisys Touch 561301 quick start guide

3M 746 instructions

Security-Center

Security-Center PROFILINE TV8165 manual

MATE

MATE Pilot Installation and operation instructions

DingLicom

DingLicom Pilot Scout 3.0 user manual

PICO PicoScope 5000 Series Manual

Popular Test Equipment manuals by other brands