PICO DrDAQ Manual
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.
USB DrDAQ
Programmer's Guide
usbdrdaqpg.en-2
Data Logger
IUSB DrDAQ Programmer's Guide
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.en
Contents
.....................................................................................................................................11 Introduction
...........................................................................................................................................1
1 Overview
...........................................................................................................................................1
2 Safety warning
...........................................................................................................................................2
3 Legal information
...........................................................................................................................................3
4 Contact details
.....................................................................................................................................42 Getting started
...........................................................................................................................................4
1 Software updates
...........................................................................................................................................4
2 USB DrDAQ scaling files (.DDS)
.....................................................................................................................................73 Writing your own software
...........................................................................................................................................7
1 About the driver
...........................................................................................................................................7
2 Installing the driver
...........................................................................................................................................7
3 Connecting the logger
...........................................................................................................................................8
4 Capture modes
...........................................................................................................................................9
5 USB DrDAQ Routines
...........................................................................................................................................9
1 Summary
...........................................................................................................................................11
2 UsbDrDaqOpenUnit
...........................................................................................................................................12
3 UsbDrDaqCloseUnit
...........................................................................................................................................13
4 UsbDrDaqGetUnitInfo
...........................................................................................................................................14
5 UsbDrDaqRun
...........................................................................................................................................15
6 UsbDrDaqReady
...........................................................................................................................................16
7 UsbDrDaqStop
...........................................................................................................................................17
8 UsbDrDaqSetInterval
...........................................................................................................................................18
9 UsbDrDaqSetTrigger
...........................................................................................................................................19
10 UsbDrDaqGetValues
...........................................................................................................................................20
11 UsbDrDaqGetTriggerTimeOffsetNs
...........................................................................................................................................21
12 UsbDrDaqGetSingle
...........................................................................................................................................22
13 UsbDrDaqOpenUnitAsync
...........................................................................................................................................23
14 UsbDrDaqOpenUnitProgress
...........................................................................................................................................24
15 UsbDrDaqGetScalings
...........................................................................................................................................25
16 UsbDrDaqSetScalings
...........................................................................................................................................26
17 UsbDrDaqSetSigGenBuiltIn
...........................................................................................................................................27
18 UsbDrDaqSetSigGenArbitrary
...........................................................................................................................................28
19 UsbDrDaqStopSigGen
...........................................................................................................................................29
20 UsbDrDaqSetDO
...........................................................................................................................................30
21 UsbDrDaqSetPWM
...........................................................................................................................................31
22 UsbDrDaqGetInput
...........................................................................................................................................32
23 UsbDrDaqStartPulseCount
...........................................................................................................................................33
24 UsbDrDaqGetPulseCount
...........................................................................................................................................34
25 UsbDrDaqEnableRGBLED
...........................................................................................................................................35
26 UsbDrDaqSetRGBLED
...........................................................................................................................................36
27 UsbDrDaqGetChannelInfo
...........................................................................................................................................37
28 PICO_STATUS values
...........................................................................................................................................39
6 Programming support
...........................................................................................................................................39
1 Introduction
...........................................................................................................................................39
2 C and C++
...........................................................................................................................................39
3 Excel
...........................................................................................................................................40
4 LabVIEW
ContentsII
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
.....................................................................................................................................424 Glossary
..............................................................................................................................................43
Index
USB DrDAQ Programmer's Guide 1
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.en
1 Introduction
1.1 Overview
The USB DrDAQ PC Data Logger is a medium-speed, multichannel voltage-input
device for sampling data using a PC. This manual explains how to use the Application
Programming Interface and drivers to write your own programs to control the unit.
You should read it in conjunction with the USB DrDAQ User's Guide.
The Software Development Kit for the USB DrDAQ is compatible with Microsoft
Windows XP, Vista and 7 (32-bit and 64-bit editions).
1.2 Safety warning
USB DrDAQ ground is connected directly to the ground of your computer. As with
most oscilloscopes and data loggers, this is done in order to minimise interference.
You should take care not to connect the ground (screw terminal, outer shell of BNC or
exposed metalwork) of USB DrDAQ to anything which may be at some voltage other
than ground, as doing so may cause damage to the unit. If in doubt, use a meter to
check that there is no significant AC or DC voltage.
For computers that do not have an earth connection (for example, laptops), it must be
assumed that USB DrDAQ is not protected by an earth (in the same way a battery
multimeter is not protected by an earth).
The scope channel on the USB DrDAQ has a maximum input voltage range of ±10 V.
The maximum input voltage for all other inputs is 0 to 5 V. Any voltage in excess
of ±30 V may cause permanent damage to the unit.
The unit contains no user serviceable parts: repair or calibration of the unit requires
specialised test equipment and must be performed by Pico Technology Limited.
Introduction2
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
1.3 Legal information
The material contained in this release is licensed, not sold. Pico Technology 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
The software in this release is for use only with Pico products or with data collected
using Pico products.
Copyright
Pico Technology claims the copyright of, and retains the rights to, all material
(software, documents etc.) contained in this release. You may copy and distribute the
entire release in its original state, but must not copy individual items within the
release other than for backup purposes.
Liability
Pico Technology and its agents shall not be liable for any loss, damage or injury,
howsoever caused, related to the use of Pico Technology equipment or software,
unless excluded by statute.
Fitness for purpose
No two applications are the same: Pico Technology cannot guarantee that its
equipment or software is suitable for a given application. It is your responsibility,
therefore, to ensure that the product is suitable for your application.
Mission-critical applications
This software is intended for use on a computer that may be running other software
products. For this reason, one of the conditions of the licence is that it excludes usage
in mission-critical applications, for example life support systems.
Viruses
This software was continuously monitored for viruses during production, but you are
responsible for virus-checking the software once it is installed.
Support
If you are dissatisfied with the performance of this software, please contact our
technical support staff, who will try to fix the problem within a reasonable time. If you
are still dissatisfied, please return the product and software to your supplier within 28
days of purchase for a full refund.
Upgrades
We provide upgrades, free of charge, from our web site. We reserve the right to
charge for updates or replacements sent out on physical media.
Trademarks
Pico Technology, PicoScope, PicoLog, DrDAQ and EnviroMon are trademarks of Pico
Technology Ltd., registered in the United Kingdom and other countries. Pico
Technology acknowledges the following product names as trademarks of their
respective owners: Windows, Excel, Visual Basic, LabVIEW, Agilent VEE, HP VEE,
Delphi.
Getting started4
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
2 Getting started
2.1 Software updates
Our software is regularly updated with new features. To check what version of the
software you are running, start PicoScope or PicoLog and select the Help | About
menu. The latest version of software can be downloaded free of charge from the
DrDAQ web site at http://www.drdaq.com. Alternatively, the latest software can be
purchased on disk or CD from Pico Technology.
To be kept up-to-date with news of new software releases join our e-mail mailing list.
This can be done from the main Pico Technology web site at http://www.picotech.
com/.
2.2 USB DrDAQ scaling files (.DDS)
The DrDAQ driver has built-in scaling for each of the built-in and Pico-supplied
sensors. You can incorporate scaling for your own sensors by adding a file called
scaling.dds (where
'scaling'
can be replaced with a name of your choice). This
file will contain the details of your sensor.
The values returned by the driver are integers that represent fixed-point decimal
numbers. For example, the driver treats pH as a value with two decimal places, so a
pH of 7.65 is returned as 765.
You can call the routine UsbDrDaqGetChannelInfo to find out how many decimal
places a channel is using, and also to get a divider that converts the integer value to
the corresponding real number. For pH, the returned divider is 100, so 765 divided by
100 gives 7.65.
For some sensors, there is more than one possible scaling available. You can call
UsbDrDaqGetScalings to get a list of valid scaling codes, then call
UsbDrDaqSetScalings to select one of them. Once selected,
UsbDrDaqGetChannelInfo will return full information about the selected scaling. If
you do not use UsbDrDaqSetScalings , the driver will automatically select the first
available scaling for each channel.
USB DrDAQ scaling files can be used to supplement the scalings built into the driver.
Several DDS files may be used, and these must be placed in the current working
directory where the USB DrDAQ software is installed. The total number of sets of
scaling data in all the files used must not exceed 99.
Each scaling file may contain more than one set of scaling data. Each scaling must
have a unique scaling number, contained in the [Scale...] section heading.
A set of typical entries from a .DDS file is shown below:
[Scale1]
Resistor=1
LongName=CustomTemperature1
ShortName=TempC
Units=C
MinValue=-40
MaxValue=120
OutOfRange=0
Places=1
Method=0
IsFast=Yes
NoOfPoints=32
4
36
24
25
36
25
USB DrDAQ Programmer's Guide 5
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.en
Raw1=2.385
Scaled1=-30
...
Raw32=1.32
Scaled32=100
[Scale2]
Resistor=2.2
LongName=CustomTemperature2
ShortName=TempF
Units=F
MinValue=32
MaxValue=160
...
[Scale3]
Resistor=3.3
LongName=CustomLight
ShortName=Light
Units=lux
MinValue=0
MaxValue=20000
...
The meanings of the terms in the .DDS file are as follows:
[Scale1]
A unique number, from 1 to 99, to identify this entry. (Pico-created numbers are
from 100 upwards.)
Resistor=1
The ID resistor value in kiloohms. In this example "1" represents 1k, "2.2"
represents 2k2 and so on.
For external sensors, this resistor should be fitted in the sensor. You must use one
of the following resistors: 1k0, 2k2, 3k3, 5k6, 7k5 or 10k. The resistor must be 1%
tolerance or better.
For internal sensors, use the following 'virtual' resistor values:
1
Sound Waveform
1200
2
Sound Level
1300
3
Voltage
1500
4
Resistance
1600
5
pH
1400
6
Temperature
1100
7
Light
1000
LongName=Temperature
Used in PicoLog
ShortName=TempC
This field is not used by USB DrDAQ running PicoScope or PicoLog.
Units=C
Getting started6
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
Displayed on graphs
MinValue=-40
MaxValue=120
Note: For PicoScope these values will determine the maximum and minimum
values displayed in Scope View. For PicoLog these values determine what
Maximum range is displayed in the Graph View (set in the Graph Options dialog).
Places=1
Number of decimal places. The options are 0, 1, 2 and 3. With places=1 the value
15.743 would be returned as 157, meaning 15.7. With places=2, the same value
would be returned as 1574.
Method=0
This specifies the scaling method. 0 specifies table lookup and 1 specifies linear
scaling.
Offset=0
Gain=1
These are the offset and gain values for linear scaling.
OutOfRange=0
This specifies what to do if the raw value is outside the range of the table lookup.
The options are:
0 - treat as a sensor failure
1 - clip the value to the minimum or maximum table value
2 - extrapolate the value using the nearest two table entries.
ScopeRange=1.25V
This is used when scaling the oscilloscope channel. It specifies the range of the
oscilloscope channel that should be used. Possible values are 10 V, 5 V, 2.5 V, and
1.25 V.
NoOfPoints=32
This is the number of table lookup points.
Raw1=2.385
Raw value for the first point in the look up table. The value is in V (volts) and
should not be greater than 2.500 V.
Scaled1=-30
Scaled value for the first point in the look up table. The units are specified by the
units parameter.
USB DrDAQ Programmer's Guide 7
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.en
3 Writing your own software
3.1 About the driver
USB DrDAQ is supplied with a kernel driver, and a DLL containing routines that you
can build into your own programs. The driver is supported by the following operating
systems:
Windows XP (SP2 or later)
Windows Vista
Windows 7
Once you have installed the software, the installation directory will contain the drivers
and a selection of examples of how to use the drivers. It also contains a copy of this
help file in PDF format.
The DLL can be used with any programming language or application that can interface
with DLLs: for example, C, Delphi, Visual Basic, Excel and LabVIEW. The SDK contains
an example for Excel, a C console example that demonstrates all of the facilities in the
driver and a LabVIEW interface and examples.
The driver supplied is a 32-bit DLL. However, it will still run on a 64-bit Windows
system if you write a 32-bit application and run it under WoW64.
The driver supports up to 64 units at one time.
3.2 Installing the driver
The driver is supplied with the USB DrDAQ SDK. You can download the latest version
of the SDK from our website at:
http://www.picotech.com/software.html
Select "USB DrDAQ" as the hardware product and then "SDK" as the software product.
The easiest way to install the USB DrDAQ kernel driver is to install PicoScope or
PicoLog. These programs are available free of charge from the Pico Technology
website. If you prefer to install the driver manually, then proceed as follows:
1. Go to the directory where you unzipped the USB DrDAQ Series SDK
2. Go to the subdirectory called system\
3. Run the program called dpinst.exe
4. Plug the device in and follow the instructions in New Hardware Wizard
3.3 Connecting the logger
Before you connect your logger, you must first install the driver .
To connect the data logger, plug the cable provided into any available USB port on
your PC. The first time you connect the unit, Windows will display a New Hardware
Wizard. Follow any instructions in the Wizard and wait for the driver to be installed.
The unit is then ready for use.
7
Writing your own software8
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
3.4 Capture modes
Three modes are available for capturing data:
BM_SINGLE: collect a single block of data and exit
BM_WINDOW: collect a series of overlapping blocks of data
BM_STREAM: collect a continuous stream of data
BM_SINGLE is useful when you wish to collect data at high speed for a short period:
for example, to collect 1000 readings in 50 milliseconds.
BM_WINDOW is useful when collecting several blocks of data at low speeds - for
example when collecting 10,000 samples over 10 seconds. Collecting a sequence of
single blocks like this would take 10 seconds for each block, so displayed data would
not be updated frequently. Using windowing, it is possible to ask for a new block more
frequently, for example every second, and to receive a block containing 9 seconds of
repeat data and 1 second of new data. The block is effectively a 10-second window
that advances one second per cycle.
BM_STREAM is useful when you need to collect data continuously for long periods. In
principle, it could be used to collect data indefinitely. Every time UsbDrDaqGetValues
is called, it returns the new readings since the last time it was called. The
noOfValues argument passed to UsbDrDaqRun must be sufficient to ensure that
the buffer does not overflow between successive calls to UsbDrDaqGetValues . For
example, if you call UsbDrDaqGetValues every second and you are collecting 500
samples per second, then noOfValues must be at least 500, or preferably 1000, to
allow for delays in the operating system.
19
14
19
19
USB DrDAQ Programmer's Guide 9
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.en
3.5 USB DrDAQ Routines
3.5.1 Summary
The following table explains each of the driver routines supplied with the USB DrDAQ
data logger:
Routine
Description
UsbDrDaqOpenUnit
open and enumerate the unit
UsbDrDaqCloseUnit
close the unit
UsbDrDaqGetUnitInfo
return various items of information about the
unit
UsbDrDaqRun
tell the unit to start capturing data
UsbDrDaqReady
indicate when UsbDrDaqRun has captured
data
UsbDrDaqStop
abort data collection
UsbDrDaqSetInterval
set the sampling speed of the unit
UsbDrDaqSetTrigger
set the trigger on the unit
UsbDrDaqGetValues
get a number of sample values after a run
UsbDrDaqGetTriggerTimeOffsetNs
returns the time between the trigger point and
the first post-trigger sample
UsbDrDaqGetSingle
get a single value from a specified channel
UsbDrDaqOpenUnitAsync
open the unit without waiting for completion
UsbDrDaqOpenUnitProgress
report progress of UsbDrDaqOpenUnitAsync
UsbDrDaqGetScalings
discover the scalings, both built-in and custom,
that are available
UsbDrDaqSetScalings
sets the scaling for a particular channel
UsbDrDaqSetSigGenBuiltIn
sets the arbitrary waveform generator using
standard waveform types
UsbDrDaqSetSigGenArbitrary
allows full control of the arbitrary waveform
generator
UsbDrDaqStopSigGen
turns the AWG off
UsbDrDaqSetDO
control the digital outputs on the unit
UsbDrDaqSetPWM
used to configure the general-purpose I/Os as
pulse-width modulation outputs
UsbDrDaqGetInput
used to configure the general-purpose I/Os as
digital inputs
UsbDrDaqStartPulseCount
used to configure the general-purpose I/Os for
pulse counting and to start counting
UsbDrDaqGetPulseCount
will return the current pulse count
UsbDrDaqEnableRGBLED
enables or disables RGB mode on the LED
UsbDrDaqSetRGBLED
used to set the colour of the LED once RGB
mode has been enabled
UsbDrDaqGetChannelInfo
returns a set of information about the currently
selected scaling for the specified channel
The driver allows you to do the following:
Identify and open the logger
Take a single reading from a particular channel
Collect a block of samples at fixed time intervals from one or more channels
Set up a trigger event for a particular channel
Get information about scalings available for a channel
Select a scaling for a channel
Control and read general-purpose I/Os
Control arbitrary waveform generator
11
12
13
14
15 14
16
17
18
19
21
21
22
23 22
24
25
26
27
28
29
30
31
32
33
34
35
36
Writing your own software10
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
You can specify a sampling interval from 1 microsecond to 1 second. The shortest
interval that the driver will accept depends on the capture mode selected.
The normal calling sequence to collect a block of data is as follows:
Check that the driver version is correct
Open the driver
Set trigger mode (if required)
Set sampling mode (channels and time per sample)
While you want to take measurements,
Run
While not ready
Wait
End while
... Get a block of data ...
End While
Close the driver
8
USB DrDAQ Programmer's Guide 11
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.en
3.5.2 UsbDrDaqOpenUnit
PICO_STATUS UsbDrDaqOpenUnit(
short * handle
)
This function opens and enumerates the unit.
Arguments:
handle: the function will write a value here that uniquely identifies
the data logger that was opened. Use this as the handle parameter
when calling any other UsbDrDaq API function.
Returns:
PICO_OK
PICO_OS_NOT_SUPPORTED
PICO_OPEN_OPERATION_IN_PROGRESS
PICO_EEPROM_CORRUPT
PICO_KERNEL_DRIVER_TOO_OLD
PICO_FW_FAIL
PICO_MAX_UNITS_OPENED
PICO_NOT_FOUND
PICO_NOT_RESPONDING
37
37
37
37
37
37
37
37
37
Writing your own software12
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
3.5.3 UsbDrDaqCloseUnit
PICO_STATUS UsbDrDaqCloseUnit(
short handle
)
This function closes the unit.
Arguments:
handle: handle returned from UsbDrDaqOpenUnit or
UsbDrDaqOpenUnitProgress
Returns:
PICO_OK
PICO_HANDLE_INVALID
11
23
37
37
USB DrDAQ Programmer's Guide 13
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.en
3.5.4 UsbDrDaqGetUnitInfo
PICO_STATUS UsbDrDaqGetUnitInfo(
short handle,
char * string,
short stringLength,
short * requiredSize,
PICO_INFO info
)
This function returns a string containing the specified item of information about the
unit.
If you want to find out the length of the string before allocating a buffer for it, then
call the function with string = NULL first.
Arguments:
handle: handle returned from UsbDrDaqOpenUnit or
UsbDrDaqOpenUnitProgress
string: a location where the function writes the requested
information, or NULL if you are only interested in the value of
requiredSize
stringLength: the maximum number of characters that the
function should write to string
requiredSize: a location where the function writes the length of
the information string before it was truncated to stringLength. If
the string was not truncated then requiredSize will be less than or
equal to stringLength.
info: the information that the driver should return. These values are
specified in picoStatus.h:
PICO_DRIVER_VERSION
PICO_USB_VERSION
PICO_HARDWARE_VERSION
PICO_VARIANT_INFO
PICO_BATCH_AND_SERIAL
PICO_CAL_DATE
PICO_KERNEL_DRIVER_VERSION
Returns:
PICO_OK
PICO_INVALID_HANDLE
PICO_NULL_PARAMETER
PICO_INVALID_INFO
PICO_INFO_UNAVAILABLE
11
23
37
37
37
37
37
Writing your own software14
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
3.5.5 UsbDrDaqRun
PICO_STATUS UsbDrDaqRun(
short handle,
unsigned long no_of_values,
UsbDrDaq_BLOCK_METHOD method
)
This function tells the unit to start capturing data.
Arguments:
handle: handle returned from UsbDrDaqOpenUnit or
UsbDrDaqOpenUnitProgress
no_of_values: the number of samples the unit should collect
method: which method to use to collect the data, from the following
list:
BM_SINGLE
BM_WINDOW
BM_STREAM
See "Capture modes " for details.
Returns:
PICO_OK
PICO_INVALID_HANDLE
PICO_USER_CALLBACK
PICO_INVALID_CHANNEL
PICO_TOO_MANY_SAMPLES
PICO_INVALID_TIMEBASE
PICO_NOT_RESPONDING
PICO_CONFIG_FAIL
PICO_INVALID_PARAMETER
PICO_NOT_RESPONDING
PICO_TRIGGER_ERROR
11
23
8
37
37
37
37
37
37
37
37
37
37
37
USB DrDAQ Programmer's Guide 15
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.en
3.5.6 UsbDrDaqReady
PICO_STATUS UsbDrDaqReady(
short handle,
short * ready
)
This function indicates when UsbDrDaqRun has captured the requested number of
samples.
Arguments:
handle: handle returned from UsbDrDaqOpenUnit or
UsbDrDaqOpenUnitProgress
ready: TRUE if ready, FALSE otherwise
Returns:
PICO_OK
PICO_INVALID_HANDLE
PICO_NOT_RESPONDING
14
11
23
37
37
37
Writing your own software16
Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.usbdrdaqpg.en
3.5.7 UsbDrDaqStop
PICO_STATUS UsbDrDaqStop(
short handle
)
This function aborts data collection.
Arguments:
handle: handle returned from UsbDrDaqOpenUnit or
UsbDrDaqOpenUnitProgress
Returns:
PICO_OK
PICO_INVALID_HANDLE
11
23
37
37
Other manuals for DrDAQ
1
This manual suits for next models
1
Table of contents
Other PICO Data Logger manuals
PICO
PICO ADC-20 User manual
PICO
PICO ADC-20 Manual
PICO
PICO PicoLog CM3 User manual
PICO
PICO USB TC-08 User manual
PICO
PICO DrDAQ User manual
PICO
PICO picolog 1000 series User manual
PICO
PICO ADC-11/10 User manual
PICO
PICO PicoLog CM3 Manual
PICO
PICO PicoLog CM3 Manual
PICO
PICO picolog 1000 series User manual
