Using the PicoScope Wrapper API Functions for Streaming Data

Post general discussions on using our drivers to write your own software here
Locked
Hitesh

Using the PicoScope Wrapper API Functions for Streaming Data

Post by Hitesh »

The Software Development Kits (SDKs) for PicoScope devices contain wrapper dynamic link library (DLL) files in a subdirectory of the Wrapper directory. The wrapper functions provided by the wrapper DLLs are for use with programming languages such as MathWorks MATLAB®, National Instruments LabVIEW and Microsoft Excel VBA that do not support features of the C programming language such as callback functions.

As of SDK release 10.5.0.32, the wrapper DLLs (SDK release 10.6.10 for the ps5000Wrap.dll for the now obsolete PicoScope 5203 and 5204) have been updated to ensure data is copied to application buffers inside the streaming callback defined in the respective Programmer’s Guides, and 64-bit versions have been made available in an x64 subdirectory in the Wrapper directory.

The source code contained in the Wrapper projects contains a description of the functions and the input and output parameters.

This post explains the sequence of calls required to capture data in streaming mode using the respective wrapper API functions.

For the PicoScope 2000 Series and PicoScope 3000 Series using the API functions provided by the ps2000.dll and ps3000.dll libraries respectively, the streaming callback mechanism operates differently. We recommend using the approaches outlined below which are based on the steps outlined in the respective Programmer’s Guides but with a few changes.

PicoScope 2000:

Applies to: PicoScope 2203, 2204, 2204A, 2205 and 2205A

Note that the size of the data buffers specified for step 6 will need to be the maximum number of samples to be collected.

This is the general procedure for reading and displaying data in fast streaming mode:

1. Open the oscilloscope using ps2000_open_unit().

2. Set the channel count on the device using the wrapper’s setChannelCount() function.

3. Select channel ranges and AC/DC switches using ps2000_set_channel().

4. Inform the wrapper of the channels that are enabled using setEnabledChannels().

5. Set the trigger using ps2000_set_trigger().

6. Set the application buffers in the wrapper for data to be copied into during fast streaming data collection
using SetBuffer() or SetAggregateBuffer() for non-aggregated or aggregated data collection respectively.

7. Inform the wrapper of the size of the application and overview buffers using setCollectionInfo() (available in versions of ps2000Wrap.dll after 1.0.1.23).

8. Start the oscilloscope running using ps2000_run_streaming_ns().

9. Call the wrapper’s PollFastStreaming() and FastStreamingReady() functions until
the wrapper indicates that data is available.

10. Call the wrapper’s GetFastStreamingDetails() function to obtain information on the data collected – number
of samples, trigger and overflow, auto stop and to indicate if the application buffer is full.

11. Display or process the data. For continuous streaming call clearFastStreamingParameters() after copying data from the Appbuffer given to the wrapper. Otherwise the Appbuffer will fill up and appBufferFull will be TRUE.

12. If required, check for overview buffer overruns by calling ps2000_overview_buffer_status().

13. Repeat steps 8 to 11 as necessary or until auto_stop or appBufferFull is TRUE.

14. Stop fast streaming using ps2000_stop().

15. Retrieve any part of the data at any time scale by calling ps2000_get_streaming_values().

16. If you require raw data, retrieve it by calling ps2000_get_streaming_values_no_aggregation().
17. Repeat steps 15 to 16 as necessary.

18. Call the wrapper’s clearFastStreamingParameters() function, particularly if you intend
to start another data collection run.

19. Close the oscilloscope by calling ps2000_close_unit().

PicoScope 3000:

Applies to: PicoScope 3224, 3424 and 3425

For this wrapper, the data buffer length(s) should be equal to the overview_buffer_size parameter specified in the call to the ps3000_run_streaming_ns() function.

1. Open the oscilloscope using ps3000_open_unit().

2. Set the channel count on the device using the wrapper’s setChannelCountI() function.

3. Select channel ranges and AC/DC switches using ps3000_set_channel().

4. Inform the wrapper of the channels that are enabled using setEnabledChannels().

5. Set the trigger using ps3000_set_trigger().

6. Set the application buffers in the wrapper for data to be copied into during fast streaming
data collection using SetDataBuffer() or
SetDataBuffers() for non-aggregated or aggregated data collection respectively.

7. Start the oscilloscope running using ps3000_run_streaming_ns().

8. Call the wrapper’s GetStreamingLatestValues()
and IsReady() functions until the wrapper indicates that data is available.

9. Call the wrapper’s AvailableData() function to obtain information on the data collected –
number of samples, trigger and overflow.

10. Display or process the data.

11. If required, check for overview buffer overruns by calling ps3000_overview_buffer_status().

12. Repeat steps 8 to 11 as necessary or until auto_stop is TRUE.

13. Stop fast streaming using ps3000_stop().

14. Retrieve any part of the data at any time scale by calling ps3000_get_streaming_values().

15. If you require raw data, retrieve it by calling ps3000_get_streaming_values_no_aggregation().

16. Repeat steps 14 to 15 as necessary.

17. Close the oscilloscope by calling ps3000_close_unit().

Other PicoScope devices:

For PicoScope using the API functions provided by the DLLs and their respective wrapper files listed below, please use the following general sequence of steps which are based on the Programmer’s Guides:
  • ps2000a.dll and ps2000aWrap.dll – PicoScope 2205MSO, 2206/7/8, 2206/7/8A, 2206/7/8B, 2405A & 2406/7/8B
  • ps3000a.dll and ps3000aWrap.dll – PicoScope 3200 A/B, 3200 MSO and 3400 A/B
  • ps4000.dll and ps4000Wrap.dll – PicoScope 4224, 4424, 4226, 4227 and 4262
  • ps4000a.dll and ps4000aWrap.dll – PicoScope 4824
  • ps5000.dll and ps5000Wrap.dll - PicoScope 5203 and 5204
  • ps5000a.dll and ps5000aWrap.dll – PicoScope 5200 A/B and 5400 A/B
  • ps6000.dll and ps6000Wrap.dll – PicoScope 6000 series devices
These wrapper dlls will copy data from the driver buffer specified to a temporary application buffer of the same size when they are registered with the wrapper and the channel is specified as being enabled. You should process the data in the temporary application buffer accordingly e.g. copy the data into a large array.

Note: replace ‘XXXX’ where used in a function call with the series name used by the DLL e.g. ‘4000’ or ‘5000a’.

Steps:

1. Open the oscilloscope using psXXXXOpenUnit().
1a. Inform the wrapper of the number of channels on the device by calling setChannelCount().
1b. [MSOs only] Inform the wrapper of the number of digital ports on the device
by calling setDigitalPortCount() (Note: this is not required for the ps2000aWrap dll).

2. Select channels, ranges and AC/DC coupling using psXXXXSetChannel().
2a. Inform the wrapper which channels have been enabled by
calling setEnabledChannels().
2b. [MSOs only] Inform the wrapper which digital ports have been enabled by
calling setEnabledDigitalPorts().

3. [MSOs only] Set the digital port using psXXXXaSetDigitalPort().

4. Use the appropriate trigger setup functions. For programming languages that do not
support structures, use the wrapper's advanced trigger setup functions.

5. [MSOs only] Use the trigger setup function psXXXXaSetTriggerDigitalPortProperties()
to set up the digital trigger if required.

6. Call psXXXXSetDataBuffer() (or for aggregated data collection psXXXXSetDataBuffers())
to tell the driver where your data buffer(s) is(are).
6a. Register the data buffer(s) with the wrapper and set the application buffer(s)
into which the data will be copied.
- For analog channels: Call setAppAndDriverBuffers() (or setMaxMinAppAndDriverBuffers()
for aggregated data collection).
- [MSOs Only] For digital ports: Call setAppAndDriverDigiBuffers() (or
setMaxMinAppAndDriverDigiBuffers()for aggregated data collection).

7. Start the oscilloscope running using psXXXXRunStreaming().

8. Loop and call GetStreamingLatestValues() and IsReady() to get data and flag when
the wrapper is ready for data to be retrieved.
8a. Call the wrapper’s AvailableData() function to obtain information on the
number of samples collected and the start index in the buffer.
8b. Call the wrapper’s IsTriggerReady() function for information on whether a
trigger has occurred and the trigger index relative to the start index in the buffer.

9. Process data returned to your application's function.

10. Call AutoStopped() if the autoStop parameter has been set to TRUE in the
call to psXXXXRunStreaming()

11. Repeat steps 8 to 10 until AutoStopped() returns true or you wish to stop data collection.

12. Call psXXXXStop(), even if the autoStop parameter was set to TRUE.

13. To disconnect a device, call psXXXXCloseUnit().

Note that the PicoScope 3000 Series devices using the ‘A’ API provided by the ps3000a.dll use a wrapper DLL that can support up to 4 devices – please refer to the Wrapper functions section in the PicoScope 3000 Series (A API) PC Oscilloscopes and MSOs Programmer’s Guide for further information.

Sorry for the long post but hopefully this will help to explain how the wrapper functions are used for streaming data capture. :D
Last edited by Hitesh on Fri Feb 17, 2017 10:21 am, edited 5 times in total.

TimOster
Newbie
Posts: 0
Joined: Mon Dec 01, 2014 5:36 pm

Re: Using the PicoScope Wrapper API Functions for Streaming

Post by TimOster »

There is no function in the dll called ps2000_set_channel_countI that I see. Is this supposed to be here?

Tim

Hitesh

Re: Using the PicoScope Wrapper API Functions for Streaming

Post by Hitesh »

Hi Tim,

Looks like it's a typo :oops:

I'll edit the post so that it reads correct ( setChannelCount() )

Regards,

F6AXK
Newbie
Posts: 0
Joined: Thu Nov 05, 2015 5:43 pm

Re: Using the PicoScope Wrapper API Functions for Streaming

Post by F6AXK »

Where to find a "Programmer's guide" including a description of Wrapper API functions (effect, arguments, returns). I use "Programmer's guide" ps2000.pg.en.pdf for PS2000 API functions, but I don't see the equivalent for Wrapper API functions.

Hitesh

Re: Using the PicoScope Wrapper API Functions for Streaming

Post by Hitesh »

Hi F6AXK,

We provide the source code for the Wrapper as part of the SDK.

The ps2000Wrap.c file (and other wrapper source code files) contain a description for each function.

Which Programming Language are you using?

Edit: Moved response to this topic.

Regards,

Locked