PICO ADC-20 Manual

Programmer's Guide
adc20.en r1
High-Resolution Data Loggers
ADC-20/ADC-24

Contents
I
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
Contents
1 Overview .............................................................................................................................. 1
2 Notices ................................................................................................................................ 2
1 Legal information ................................................................................................................................... 2
2 Trademarks ............................................................................................................................................ 2
3 Getting started .................................................................................................................... 3
1 Installing the software ........................................................................................................................... 3
2 Connecting the data logger .................................................................................................................. 3
4 Concepts ............................................................................................................................. 4
1 Recording methods ................................................................................................................................ 4
2 Windows driver ....................................................................................................................................... 4
3 Scaling .................................................................................................................................................... 4
5 Driver functions .................................................................................................................. 5
1 HRDLCloseUnit – shuts down unit ........................................................................................................ 6
2 HRDLCollectSingleValueAsync – sample a single value, non-blocking .............................................. 7
3 HRDLGetMinMaxAdcCounts – return the maximum and minimum ADC count ................................ 8
4 HRDLGetNumberOfEnabledChannels – return the number of analog channels enabled ................. 9
5 HRDLGetSingleValue – take one sample for the specified channel ................................................. 10
6 HRDLGetSingleValueAsync – retrieves reading after call to HRDLCollectSingleValueAsync() ...... 11
7 HRDLGetTimesAndValues – return time-stamped samples ............................................................ 13
8 HRDLGetUnitInfo – returns unit information as character string ...................................................... 14
9 HRDLGetValues – return samples for each enabled channel ........................................................... 16
10 HRDLOpenUnit – open a data logger ................................................................................................ 17
11 HRDLOpenUnitAsync – open a unit without blocking the calling thread ........................................ 18
12 HRDLOpenUnitProgress – check progress of an asynchronous open operation .......................... 19
13 HRDLReady – find out if readings are ready to be collected ........................................................... 20
14 HRDLRun – start sampling ............................................................................................................... 21
15 HRDLSetAnalogInChannel – enable or disable an analog channel ................................................ 22
16 HRDLSetDigitalIOChannel – set a digital output or input (ADC-24 only) ........................................ 23
17 HRDLSetInterval – set the sampling time interval ........................................................................... 25
18 HRDLSetMains – set the mains noise rejection frequency ............................................................. 26
19 HRDLStop – stop the device when streaming ................................................................................. 27
6 Sequence of calls and data flow ..................................................................................... 28
1 Streaming recording methods ............................................................................................................. 28
1 Collecting a block of data ........................................................................................................ 28
2 Collecting windowed or streaming data ................................................................................. 29
2 Single-value recording methods .......................................................................................................... 30
1 Collecting a single reading, blocking ...................................................................................... 30
2 Collecting a single reading, non-blocking ............................................................................... 30
7 Glossary ............................................................................................................................ 31

ADC-20/ADC-24 Programmer's Guide 1
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
1 Overview
The ADC-20 and ADC-24 High-Resolution Data Loggers are multichannel, high-accuracy USB data
loggers for use with PCs. They require no external power supply.
We provide 32-bit and 64-bit Windows drivers to allow you to control the data loggers from your
own software. These drivers are included in the PicoSDK package, which you can download from
www.picotech.com/downloads.
Example code in a variety of programming languages can be downloaded from the "picotech"
organization on GitHub.
The hardware and software are compatible with Microsoft Windows 7, 8 and 10.

Notices2
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
2 Notices
2.1 Legal information
The material contained in this release is licensed, not sold. Pico Technology Limited 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 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 Limited 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. As 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 license is that it excludes
usage in mission-critical applications, such as 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.
2.2 Trademarks
Pico Technology Limited and PicoLog are trademarks of Pico Technology Limited, registered in
the United Kingdom and other countries.
PicoLog and Pico Technology are registered in the U.S. Patent and Trademark Office.
Windows and Excel are registered trademarks of Microsoft Corporation in the USA and other
countries.

ADC-20/ADC-24 Programmer's Guide 3
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
3 Getting started
3.1 Installing the software
Before you connect the ADC-20 or ADC-24 to your computer for the first time, you must install the
driver using PicoSDK. You can download 32-bit and 64-bit versions of PicoSDK from
www.picotech.com/downloads.
3.2 Connecting the data logger
When you have installed the driver, connect the data logger's USB cable to a spare USB port on
your computer and wait until Windows displays the message "Device is ready to use".

Concepts4
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
4 Concepts
4.1 Recording methods
The ADC-20/ADC-24 driver provides three methods of recording data. All these methods support
USB 1.1 and later.
· Streaming. The driver constantly polls the device, and samples are placed in a buffer until
retrieved by your application. Precise sample timing is controlled by the unit.
· Single value (blocking). You make a single request for a sample, blocking the calling thread, and
when the sample has been received the driver returns the value to your application.
· Single value (non-blocking). You make a single request for a sample without blocking the calling
thread, and when the sample has been received the driver returns the value to your application.
4.2 Windows driver
The picohrdl.dll dynamic link library (DLL) in the lib subdirectory of your SDK installation is a
driver that allows you to program your ADC-20 or ADC-24 data logger. It is supplied in 32-bit and
64-bit versions. The driver exports the 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. It can also be used with programs like Microsoft Excel. The driver supports
Windows 7, 8 and 10.
4.3 Scaling
To convert from ADC values to volts, first obtain the minimum and maximum ADC values for the
selected channel by calling HRDLGetMinMaxAdcCounts() in the driver. Next, scale the ADC
value to the voltage range you specified when you called HRDLSetAnalogInChannel(). You can
calculate the voltage range programmatically by using
Vmax = 2500 mV / (2^r)
where ris the range constant you supplied to HRDLSetAnalogInChannel() (0 for ±2500 mV, 1
for ±1250 mV and so on).
You can then use Vmax to calculate the scaled voltage, V, with the following formula
V = (raw_ADC_value / max_ADC_Value) * Vmax
where raw_ADC_value is the reading from the device and max_ADC_value is the max ADC value for
the device obtained from HRDLGetMinMaxAdcCounts().

ADC-20/ADC-24 Programmer's Guide 5
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
5 Driver functions
The following sections describe the functions available to an application using the ADC-20 and
ADC-24. All functions are C functions using the standard call naming convention (__stdcall) and
are exported with both decorated and undecorated names.

Driver functions6
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
5.1 HRDLCloseUnit – shuts down unit
int16_t HRDLCloseUnit
(int16_t handle
)
Shuts down an ADC-20 or ADC-24 device.
Arguments
handle, device identifier returned by HRDLOpenUnit()
Returns
1 if a valid handle is passed
0 if not

ADC-20/ADC-24 Programmer's Guide 7
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
5.2 HRDLCollectSingleValueAsync – sample a single value, non-blocking
int16_t HRDLCollectSingleValueAsync
(int16_t handle,
int16_t channel,
int16_t range,
int16_t conversionTime,
int16_t singleEnded
)
This function starts the unit sampling one value without blocking the calling application's flow.
Used in conjunction with HRDLGetSingleValueAsync() and HRDLReady().
Arguments
handle, device identifier returned by HRDLOpenUnit()
channel, Channel number to convert. If the channel is not valid then the function will fail.
range, The voltage range to be used. If the range is not valid, the function
HRDLGetSingleValueAsync() will return 0.
conversionTime, The time interval in which the sample should be converted. If the conversion
time is invalid, the function HRDLGetSingleValueAsync() will fail and return 0.
singleEnded, The type of voltage to be measured:
0: differential
<>0: single-ended
Returns
1 if a valid handle is passed and the settings are correct
0 if not

Driver functions8
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
5.3 HRDLGetMinMaxAdcCounts – return the maximum and minimum
ADC count
int16_t HRDLGetMinMaxAdcCounts
(int16_t handle,
int32_t * minAdc,
int32_t * maxAdc,
int16_t channel
)
This function returns the maximum and minimum ADC count available for the device referenced by
handle.
Arguments
· handle, device identifier returned by HRDLOpenUnit()
· minAdc, Pointer to an int32_t, used to return the minimum ADC count available for the unit
referred to by handle
· maxAdc, Pointer to an int32_t, used to return the maximum ADC count available for the unit
referred to by handle
· channel, Channel number for which maximum and minimum ADC count are required
Returns
1 if a valid handle is passed
0 if not

ADC-20/ADC-24 Programmer's Guide 9
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
5.4 HRDLGetNumberOfEnabledChannels – return the number of analog
channels enabled
int16_t HRDLGetNumberOfEnabledChannels
(int16_t handle,
int16_t * nEnabledChannels
)
This function returns the number of analog channels enabled.
Arguments
handle, device identifier returned by HRDLOpenUnit()
nEnabledChannels, pointer to an int16_t where the number of channels enabled will be
written
Returns
1 if a valid handle is passed
0 if not

Driver functions10
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
5.5 HRDLGetSingleValue – take one sample for the specified channel
int16_t HRDLGetSingleValue
(int16_t handle,
int16_t channel,
int16_t range,
int16_t conversionTime,
int16_t singleEnded,
int16_t * overflow
int32_t * value
)
This function takes one sample for the specified channel at the selected voltage range and
conversion time.
Arguments
handle, device identifier returned by HRDLOpenUnit()
channel, The channel number to convert.
ADC-20: 1 to 8
ADC-24: 1 to 16
If the channel is not valid then the function will fail and return 0.
range, the voltage range to be used. See HRDLSetAnalogInChannel() for possible values. If
the range is not valid, the function will return 0.
conversionTime, The time interval in which the sample should be converted. See
HRDLSetInterval() for possible values. If the conversion time is invalid, the function will fail
and return 0.
singleEnded, The type of voltage to be measured.
0: differential
<>0: single-ended
overflow, pointer to a bit field that indicates when the voltage on a channel has exceeded the
upper or lower limits.
Bit 0: Channel 1
...
Bit 15: Channel 16
value, pointer to an int32_t where the ADC value will be written.
Returns
1 if a valid handle is passed and settings are correct
0 if not
If the function fails, call HRDLGetUnitInfo() with info = HRDL_ERROR (7) to obtain the
error code. If the error code is HRDL_SETTINGS (5), then call HRDLGetUnitInfo() again with
info = HRDL_SETTINGS_ERROR (8) to determine the settings error.

ADC-20/ADC-24 Programmer's Guide 11
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
5.6 HRDLGetSingleValueAsync – retrieves reading after call to
HRDLCollectSingleValueAsync()
int16_t HRDLGetSingleValueAsync
(int16_t handle,
int32_t * value,
int16_t * overflow
)
This function retrieves the reading when HRDLCollectSingleValueAsync() has been called.
Arguments
handle, device identifier returned by HRDLOpenUnit()
value, pointer to an int32_t where the ADC value will be written
overflow, pointer to a value that indicates when the voltage on a channel has exceeded the upper
or lower limits.
Bit 0: Channel 1
...
Bit 15: Channel 16
Returns
1 if a valid handle is passed and the function succeeds
0 if not
Sample code
Code extract to get a single value reading without blocking the calling thread:
void main()
{
BOOL bConversionFinished =FALSE;
int16_t channelNo;
int32_t value;
int16_t handle;
// Open and initialize the unit
...
// Set the channel parameters
channelNo =HRDL_ANALOG_IN_CHANNEL_1;
range =HRDL_2500_MV;
singleEnded =TRUE;
bConversionFinished =FALSE;
while (true)
{
PollSingleValue(handle,
&bConversionFinished,
&value,
channelNo,
range,

Driver functions12
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
singleEnded);
if (bConversionFinished == TRUE)
{
// Do something with the value
channelNo++;
// This would be HRDL_ANALOG_IN_CHANNEL_8 for the ADC-20
if (channelNo >HRDL_ANALOG_IN_CHANNEL_16)
{
channelNo =HRDL_ANALOG_IN_CHANNEL_1;
}
}
else
{
// Do something else while waiting for the reading from the unit
}
}
}
void PollSingleValue(int16_t handle,
BOOL *bConversionFinished,
int32_t *lValue,
int16_t channel,
int16_t range,
int16_t singleEnded)
{
static BOOL bStartConversion =FALSE;
int16_t overflow;
// Test to see if the conversion has finished
if (bStartedConversion)
{
if (HRDLReady(handle))
{
HRDLGetSingleValueAsync(handle, lValue, &overflow);
bConversionFinished =TRUE;
bConversionStarted =FALSE;
}
}
// Test to see if no conversion is in progress
if (!bStartedConversion)
{
// Start the conversion going
bStartedConversion =HRDLCollectSingleValueAsync(handle,
channel,
range,
conversionTime,
singleEnded);
bConversionFinished =TRUE;
}
}

ADC-20/ADC-24 Programmer's Guide 13
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
5.7 HRDLGetTimesAndValues – return time-stamped samples
int32_t HRDLGetTimesAndValues
(int16_t handle,
int32_t * times,
int32_t * values,
int16_t * overflow,
int32_t noOfValues
)
This function returns the requested number of samples for each enabled channel and the times
when the samples were taken, so the values array needs to be (number of values) x (number of
enabled channels). When one or more of the digital IOs are enabled as inputs, they count as one
additional channel. The function informs the user if the voltages for any of the enabled channels
have overflowed.
Arguments
handle, device identifier returned by HRDLOpenUnit()
times, pointer to an int32_t where times will be written
values, pointer to an int32_t where sample values will be written. If more than one channel is
active, the samples are interleaved. If digital channels are enabled then they are always the first
values. See table below for the order in which data are returned.
overflow, pointer to an int16_t indicating any inputs that have exceeded their maximum
voltage range. Channels with overvoltages are indicated by a high bit, with the LSB indicating
channel 1 and the MSB channel 16.
noOfValues, the number of samples to collect for each active channel.
Returns
A non-zero number if successful indicating the number of values returned,
0 if the call failed or no values available
Ordering of returned data (example)
When two analog channels (e.g. 1 and 5) are enabled and a digital channel is set as an input, the
data are returned in the following order:
Sample No: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 . n-3 n-2 n-1
Channel: DI 1 5 DI 1 5 DI 1 5 DI 1 5 DI 1 5 . DI 1 5
where nrepresents the value returned by the function and DI the digital inputs.
The channels are always ordered from channel 1 up to the maximum channel number (ADC-24:
channel 16, ADC-20: channel 8). If one or more digital channels are set as inputs then the first
sample contains the digital channels.
Digital inputs
The digital channels are represented by a binary bit pattern with 0 representing off, and 1
representing on. Digital input 1 is in bit 0.

Driver functions14
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
5.8 HRDLGetUnitInfo – returns unit information as character string
int16_t HRDLGetUnitInfo
(int16_t handle,
int8_t * string,
int16_t stringLength,
int16_t info
)
This function writes information about the ADC-20 or ADC-24 device to a character string. If the
logger fails to open, only info = HRDL_ERROR (7) is available to explain why the last open unit
call failed. When retrieving the driver version, the handle value is ignored.
Arguments
handle, identifier of the device from which information is required. If an invalid handle is passed,
the error code from the last unit that failed to open is returned (as if info = HRDL_ERROR),
unless info = HRDL_DRIVER_VERSION and then the driver version is returned.
string, pointer to the int8_t string buffer in the calling function where the unit information
string (selected with info) will be stored. If a null pointer is passed, no information will be written.
stringLength, Length of the int8_t string buffer. If the string is not long enough to accept all
of the information, only the first stringLength characters are returned.
info, Enumerated type (listed below) specifying what information is required from the driver.
Returns
The length of the string written to the int8_t string buffer, string, by the function.
If one of the parameters is out of range, or a null pointer is passed for string, the function will
return zero.

ADC-20/ADC-24 Programmer's Guide 15
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
Values of info
Value of info
Description
Example
HRDL_DRIVER_VERSION (0)
The version of picohrdl.dll
1.0.0.1
HRDL_USB_VERSION (1)
The type of USB to which the
unit is connected
1.1
HRDL_HARDWARE_VERSION (2)
The hardware version of the
HRDL attached
1
HRDL_VARIANT_INFO (3)
Information about the type of
HRDL attached
24
HRDL_BATCH_AND_SERIAL (4)
Batch and serial numbers of the
unit
CMY02/116
HRDL_CAL_DATE (5)
Calibration date of the unit
09Sep05
HRDL_KERNEL_DRIVER_VERSION (6)
Kernel driver version
HRDL_ERROR (7)
One of the error codes listed in
Error codes below
4
HRDL_SETTINGS (8)
One of the error codes listed in
Settings Error Codes below
Error codes (when info = HRDL_ERROR)
Error code
Description
HRDL_OK (0)
The unit is functioning correctly
HRDL_KERNEL_DRIVER (1)
The picopp.sys file is to old to support this
product
HRDL_NOT_FOUND (2)
No data logger could be found
HRDL_CONFIG_FAIL (3)
Unable to download firmware
HRDL_ERROR_OS_NOT_SUPPORTED (4)
The operating system is not supported by this
device
HRDL_MAX_DEVICES (5)
The maximum number of units allowed are
already open
Settings Error Codes (when info = HRDL_SETTINGS)
Settings Error Code
Description
SE_CONVERSION_TIME_OUT_OF_RANGE (0)
The conversion time parameter is out of range
SE_SAMPLEINTERVAL_OUT_OF_RANGE (1)
The sample time interval is out of range
SE_CONVERSION_TIME_TOO_SLOW (2)
The conversion time chosen is not fast enough
to convert all channels within the sample
interval
SE_CHANNEL_NOT_AVAILABLE (3)
The channel being set is valid but not currently
available
SE_INVALID_CHANNEL (4)
The channel being set is not valid for this device
SE_INVALID_VOLTAGE_RANGE (5)
The voltage range being set for this device is
not valid
SE_INVALID_PARAMETER (6)
One or more parameters are invalid
SE_CONVERSION_IN_PROGRESS (7)
A conversion is in progress for a single
asynchronous operation
SE_COMMUNICATION_FAILED (8)
The PC has lost communication with the device
SE_OK (9)
All settings have been completed successfully

Driver functions16
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
5.9 HRDLGetValues – return samples for each enabled channel
int32_t HRDLGetValues
(int16_t handle,
int32_t * values,
int16_t * overflow,
int32_t noOfValues
)
This function returns the requested number of samples for each enabled channel, so the size of
the values array needs to be (number of values) x (number of enabled channels). When one or
more of the digital IOs are enabled as inputs, they count as one additional channel. The function
informs the user if the voltages of any of the enabled channels have overflowed.
Arguments
handle, device identifier returned by HRDLOpenUnit()
values, pointer to an int32_t where the sample values are written. If more than one channel is
active, the samples are interleaved. If digital channels are enabled then they are always the first
value. See table below for the order in which data are returned.
overflow, pointer to an int16_t indicating any inputs that have exceeded their maximum
voltage range. Channels with overvoltages are indicated by a high bit, with the LSB indicating
channel 1 and the MSB channel 16.
noOfValues, the number of samples to collect for each active channel.
Returns
A non-zero number if successful indicating the number of values returned, or
0 if the call failed or no values available
Ordering of returned data (example)
When two analog channels (such as 1 and 5) are enabled and a digital channel is set as an input,
the data are returned in the following order.
Sample No: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 . n-3 n-2 n-1
Channel: DI 1 5 DI 1 5 DI 1 5 DI 1 5 DI 1 5 . DI 1 5
where nrepresents the total number of values returned by the function and DI the digital inputs.
The channels are always ordered from channel 1 up to the maximum channel number (ADC-24:
channel 16, ADC-20: channel 8). If one or more digital channels are set as inputs, and digital inputs
are enabled by calling HRDLSetDigitalIOChannel() with enabledDigitalIn=1, the first
sample in each group contains the digital channels.
Digital inputs
The digital channels are represented by a binary bit pattern with 0 representing off and 1
representing on. Digital input 1 is in bit 0.

ADC-20/ADC-24 Programmer's Guide 17
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved. adc20.en r1
5.10 HRDLOpenUnit – open a data logger
int16_t HRDLOpenUnit
(void
)
This function opens an ADC-20 or ADC-24 device. The API driver can support up to 20 units.
Arguments
None
Returns
–1 if the unit fails to open
0 if no unit is found
1 handle to the device opened

Driver functions18
Copyright © 2005–2019 Pico Technology Ltd. All rights reserved.adc20.en r1
5.11 HRDLOpenUnitAsync – open a unit without blocking the calling thread
int16_t HRDLOpenUnitAsync
(void
)
Opens an ADC-20 or ADC-24 device without blocking the calling thread.
Arguments
None
Returns
0 if there is already an open operation in progress
1 if the open operation has been initiated