USB DrDAQ Data Logger Programmer's Guide usbdrdaqpg.en-2 Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.
USB DrDAQ Programmer's Guide I Contents 1 Introduction .....................................................................................................................................1 1 Overview ...........................................................................................................................................1 2 Safety warning ...........................................................................................................................................
II Contents 4 Glossary .....................................................................................................................................42 Index ..............................................................................................................................................43 usbdrdaqpg.en Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.
USB DrDAQ Programmer's Guide 1 Introduction 1.1 Overview 1 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 1.3 Introduction 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.
USB DrDAQ Programmer's Guide 1.4 3 Contact details Address: Web site: Pico Technology James House Colmworth Business Park ST NEOTS Cambridgeshire PE19 8YP United Kingdom Tel: +44 1480 396395 Fax: +44 1480 396296 www.picotech.com Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.
4 Getting started 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.
USB DrDAQ Programmer's Guide 5 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.
6 Getting started 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.
USB DrDAQ Programmer's Guide 3 Writing your own software 3.1 About the driver 7 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.
8 3.4 Writing your own software 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.
USB DrDAQ Programmer's Guide 9 3.5 USB DrDAQ Routines 3.5.
10 Writing your own software 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 8 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 ...
USB DrDAQ Programmer's Guide 3.5.2 11 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.
12 3.5.3 Writing your own software UsbDrDaqCloseUnit PICO_STATUS UsbDrDaqCloseUnit( short handle ) This function closes the unit. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress Returns: usbdrdaqpg.en PICO_OK 37 PICO_HANDLE_INVALID 11 or 23 37 Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.
USB DrDAQ Programmer's Guide 3.5.4 13 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.
14 3.5.5 Writing your own software 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 UsbDrDaqOpenUnitProgress 11 or 23 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 Returns: usbdrdaqpg.
USB DrDAQ Programmer's Guide 3.5.6 15 UsbDrDaqReady PICO_STATUS UsbDrDaqReady( short handle, short * ready ) This function indicates when UsbDrDaqRun samples. Arguments: 14 has captured the requested number of handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 ready: TRUE if ready, FALSE otherwise Returns: PICO_OK 37 PICO_INVALID_HANDLE PICO_NOT_RESPONDING Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. 37 37 usbdrdaqpg.
16 3.5.7 Writing your own software UsbDrDaqStop PICO_STATUS UsbDrDaqStop( short handle ) This function aborts data collection. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress Returns: usbdrdaqpg.en PICO_OK 37 PICO_INVALID_HANDLE 11 or 23 37 Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.
USB DrDAQ Programmer's Guide 3.5.8 17 UsbDrDaqSetInterval PICO_STATUS UsbDrDaqSetInterval( short handle, unsigned long * us_for_block, unsigned long ideal_no_of_samples, short * channels, short no_of_channels ) This function sets the sampling rate of the unit. The fastest possible sampling interval is 1 microsecond, when the number of samples is 8129 divided by the number of channels active and the capture mode 8 is BM _SINGLE.
18 3.5.9 Writing your own software UsbDrDaqSetTrigger PICO_STATUS UsbDrDaqSetTrigger( short handle, unsigned short enabled, unsigned short auto_trigger, unsigned short auto_ms, unsigned short channel, unsigned short dir, unsigned short threshold, unsigned short hysteresis, float delay ) This function sets up the trigger, which controls when the unit starts capturing data.
USB DrDAQ Programmer's Guide 19 3.5.10 UsbDrDaqGetValues PICO_STATUS UsbDrDaqGetValues( short handle, short * values, unsigned long * noOfValues, unsigned short * overflow, unsigned long * triggerIndex ) This function is used to get values after calling UsbDrDaqRun Arguments: 14 . handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 values: an array of sample values returned by the function.
20 Writing your own software 3.5.11 UsbDrDaqGetTriggerTimeOffsetNs PICO_STATUS UsbDrDaqGetTriggerTimeOffsetNs( short handle _int64 * time ) This function returns the time between the trigger point and the first post-trigger sample. This is calculated using linear interpolation. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 time: a location where the driver writes the trigger time in nanoseconds. Returns: usbdrdaqpg.
USB DrDAQ Programmer's Guide 21 3.5.12 UsbDrDaqGetSingle PICO_STATUS UsbDrDaqGetSingle( short handle, USB_DrDAQ_INPUTS channel, unsigned short * value unsigned short * overflow ) This function returns a single sample value from the specified input channel.
22 Writing your own software 3.5.13 UsbDrDaqOpenUnitAsync PICO_STATUS UsbDrDaqOpenUnitAsync( short * status ) This function opens a USB DrDAQ data logger without waiting for the operation to finish. You can find out when it has finished by periodically calling UsbDrDaqOpenUnitProgress 23 until that function returns a non-zero value and a valid data logger handle. The driver can support up to 64 data loggers.
USB DrDAQ Programmer's Guide 23 3.5.14 UsbDrDaqOpenUnitProgress PICO_STATUS UsbDrDaqOpenUnitProgress( short * handle, short * progress, short * complete ) This function checks on the progress of UsbDrDaqOpenUnitAsync Arguments: 22 . handle: a pointer to where the function should store the handle of the opened data logger, if the operation was successful. Use this as the handle parameter when calling any other USB DrDAQ API function.
24 Writing your own software 3.5.15 UsbDrDaqGetScalings PICO_STATUS UsbDrDaqGetScalings( short handle USB_DRDAQ_INPUTS channel, short * nScales, short * currentScale, char * names, short namesSize This function discovers the scalings, both built-in and custom, that are available for a particular channel. Arguments: handle: handle returned from UsbDrDaqOpenUnit Returns: PICO_OK 37 PICO_NOT_FOUND 37 PICO_INVALID_CHANNEL usbdrdaqpg.
USB DrDAQ Programmer's Guide 25 3.5.16 UsbDrDaqSetScalings PICO_STATUS UsbDrDaqSetScalings( short handle USB_DRDAQ_INPUTS channel, short scalingNumber ) This function sets the scaling for a particular channel.
26 Writing your own software 3.5.17 UsbDrDaqSetSigGenBuiltIn PICO_STATUS UsbDrDaqSetSigGenBuiltIn( short handle, long offsetVoltage, unsigned long pkToPk, short frequency, USB_DRDAQ_WAVE waveType ) This function sets the arbitrary waveform generator using standard waveform types. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 offsetVoltage: The offset voltage in microvolts. The offset voltage must be in the range -1.5 V to 1.5 V.
USB DrDAQ Programmer's Guide 27 3.5.18 UsbDrDaqSetSigGenArbitrary PICO_STATUS UsbDrDaqSetSigGenArbitrary( short handle, long offsetVoltage, unsigned long pkToPk, short * arbitraryWaveform, short arbitraryWaveformSize, long updateRate ) This function allows full control of the arbitrary waveform generator by allowing an arbitrary waveform to be passed to the driver.
28 Writing your own software 3.5.19 UsbDrDaqStopSigGen PICO_STATUS UsbDrDaqStopSigGen( short handle, ) This function turns the AWG off. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress Returns: usbdrdaqpg.en PICO_OK 37 PICO_NOT_FOUND 37 PICO_NOT_RESPONDING 11 or 23 37 Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.
USB DrDAQ Programmer's Guide 29 3.5.20 UsbDrDaqSetDO PICO_STATUS UsbDrDaqSetDO( short handle, USB_DRDAQ_GPIO IOChannel, short value ) This function is used to configure the general-purpose I/Os as digital outputs. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 IOChannel: One of the following: USB_DRDAQ_GPIO_1 = 1, USB_DRDAQ_GPIO_2, USB_DRDAQ_GPIO_3, USB_DRDAQ_GPIO_4 value: Used to set or clear the digital output.
30 Writing your own software 3.5.21 UsbDrDaqSetPWM PICO_STATUS UsbDrDaqSetPWM( short handle, USB_DRDAQ_GPIO IOChannel, unsigned short period, unsigned char cycle ) This function is used to configure the general-purpose I/Os as pulse-width modulation outputs. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 IOChannel: GPIOs 1 and 2 can be used as PWM outputs. period: The period of the waveform in microseconds.
USB DrDAQ Programmer's Guide 31 3.5.22 UsbDrDaqGetInput PICO_STATUS UsbDrDaqGetInput( short handle, USB_DRDAQ_GPIO IOChannel, short pullUp, short * value ) This function is used to configure the general-purpose I/Os as digital inputs. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 IOChannel: All GPIOs can be used for digital inputs. pullUp: Used to specify whether pull-up resistor is used.
32 Writing your own software 3.5.23 UsbDrDaqStartPulseCount PICO_STATUS UsbDrDaqStartPulseCount( short handle, USB_DRDAQ_GPIO IOChannel, short direction ) This function is used to configure the general-purpose I/Os for pulse counting and to start counting. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 IOChannel: GPIOs 1 and 2 can be used as pulse-counting inputs. direction: The direction of the edges to count (0:rising, 1:falling) Returns: usbdrdaqpg.
USB DrDAQ Programmer's Guide 33 3.5.24 UsbDrDaqGetPulseCount PICO_STATUS UsbDrDaqGetPulseCount( short handle, USB_DRDAQ_GPIO IOChannel, short * count ) This function will return the current pulse count. It should be called after pulse counting has been started using UsbDrDaqStartPulseCount 32 . Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 IOChannel: GPIO of interest. count: A location where the driver will write the current count.
34 Writing your own software 3.5.25 UsbDrDaqEnableRGBLED PICO_STATUS UsbDrDaqEnableRGBLED( short handle, short enabled ) This function enables or disables RGB mode on the LED. Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 enabled: If non-zero, RGB mode is enabled. If zero RGB mode is disabled and the LED returns to normal operation (flashing when sampling). Returns: usbdrdaqpg.
USB DrDAQ Programmer's Guide 35 3.5.26 UsbDrDaqSetRGBLED PICO_STATUS UsbDrDaqSetRGBLED( short handle, unsigned short unsigned short unsigned short red, green, blue ) This function is used to set the colour of the LED once RGB mode has been enabled using USBDRDaqEnableRGBLED 34 . Arguments: handle: handle returned from UsbDrDaqOpenUnit UsbDrDaqOpenUnitProgress 11 or 23 red, green, blue: Components of the requred LED colour, in the range 0 to 255.
36 Writing your own software 3.5.27 UsbDrDaqGetChannelInfo PICO_STATUS UsbDrDaqGetChannelInfo( short handle, float * min, float * max, short * places, short * divider, USB_DRDAQ_INPUTS channel ) This procedure returns a set of information about the currently selected scaling for the specified channel. If a parameter is not required, you can pass a null pointer to the routine.
USB DrDAQ Programmer's Guide 37 3.5.
38 Writing your own software 20 PICO_DELAY 21 22 23 PICO_SOURCE_DETAILS PICO_CONDITIONS PICO_USER_CALLBACK 24 PICO_DEVICE_SAMPLING 25 26 27 28 29 PICO_NO_SAMPLES_AVAILABLE PICO_SEGMENT_OUT_OF_RANGE PICO_BUSY PICO_STARTINDEX_INVALID PICO_INVALID_INFO 2A PICO_INFO_UNAVAILABLE 2B PICO_INVALID_SAMPLE_INTERVAL 2C 2D 36 PICO_TRIGGER_ERROR PICO_MEMORY PICO_DELAY_NULL 37 PICO_INVALID_BUFFER 3A 3B 3C PICO_CANCELLED PICO_SEGMENT_NOT_USED PICO_INVALID_CALL 3F 41 43 PICO_NOT_USED PICO_INVALID_STATE
USB DrDAQ Programmer's Guide 3.6 Programming support 3.6.1 Introduction 39 We supply examples for the following programming languages: C and C++ Excel 39 LabVIEW 3.6.2 39 40 C and C++ C To compile the program, create a new project for an Application containing the following files: usbdrdaqcon.c and usbdrdaq.lib (Microsoft Visual C 32-bit applications). or usbdrdaqbc.lib (Borland 32-bit applications) The following files must be in the compilation directory: usbdrdaqapi.h picostatus.
40 3.6.4 Writing your own software LabVIEW The SDK contains a library of VIs that can be used to control the USB DrDAQ and two examples of using these VIs. DrDAQBlockExample.vi is a simple block mode example that demonstrates using block mode on a single channel with a trigger. DrDAQStreamingExample.vi demonstrates streaming mode acquisition on all channels with triggering. It also demonstrates use of the general-purpose I/Os, the arbitrary waveform generator, channel scaling and the RGB LED.
USB DrDAQ Programmer's Guide 41 UsbDrDaqStartStreaming.vi – starts the device streaming data after the USB DrDAQ has been set up using UsbDrDaqSettings.vi. The "number of values" input is used by the driver to create its buffer. Once this VI has been called, values can be obtained from the driver using UsbDrDaqGetStreamingData.vi. Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. usbdrdaqpg.
42 4 Glossary Glossary Analog bandwidth. The input frequency at which the measured signal amplitude is 3 decibels below the true signal amplitude. Buffer size. The size of the oscilloscope buffer memory, measured in samples. The buffer allows the oscilloscope to sample data faster than it can transfer it to the computer. Device Manager. Device Manager is a Windows program that displays the current hardware configuration of your computer.
USB DrDAQ Programmer's Guide 43 Index UsbDrDaqSetInterval 17 UsbDrDaqSetPWM 30 UsbDrDaqSetRGBLED 6 64-bit Windows 7 UsbDrDaqSetTrigger Arbitrary waveform generator Asynchronous operation 27 8 E B Excel BM_SINGLE mode 8 BM_STREAM mode 8 BM_WINDOW mode 8 39 G Grounding C 1 I 39 Information on unit, obtaining Installation 7 C++ 39 Calibration 1 Capture modes BM_SINGLE LabVIEW Connecting to the PC 40 Laptops 1 LED 34, 35 Legal information 12 7 2 D N Data, reading 19, 21 Digital Out
44 Index R Repair 1 Running a unit 14 S Safety warning 1 Sampling interval, setting Scaling 25 Scaling files 4 Signal Generator 17 26, 28 Software updates 4 Stopping a unit 16 Streaming 8 T Trigger, setting 18 U Unit information, obtaining 13 W Windows XP/Vista/Windows 7 support 7 WoW64 usbdrdaqpg.en 7 Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.
USB DrDAQ Programmer's Guide Copyright © 2010-2011 Pico Technology Ltd. All rights reserved. 45 usbdrdaqpg.
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 usbdrdaqpg.en-2 03.02.11 Copyright © 2010-2011 Pico Technology Ltd. All rights reserved.
