NAME

Lab::Zhinst - Perl bindings to the LabOne API of Zurich Instruments

SYNOPSIS

use Lab::Zhinst;

####################################################

# LabOne's "Getting Started" example in Perl:

# Create connection object
my ($rv, $connection) = Lab::Zhinst->Init();
if ($rv) {
    # handle error ...
}
# Connect to DataServer at localhost, port 8004.
($rv)  = $connection->Connect("localhost", 8004);

# Set all demodulator rates of device dev1046 to 150 Hz.
my ($rv) = $connection->SetValueD("/dev1046/demods/*/rate", 150);

####################################################

# Read x and y value from the Lock-In demodulator:

my $device = "/dev3281";
my ($rv, $hash_ref) = $connection->GetDemodSample("$device/DEMODS/0/SAMPLE");
printf("x = %g, y = %g\n", $hash_ref->{x}, $hash_ref->{y});

INSTALLATION

Linux

Download the LabOne API for Linux from https://www.zhinst.com.
After unpacking, copy the header API/C/include/ziAPI.h and the library API/C/lib/ziAPI-linux64.so into directories searched by the compiler and linker (e.g. /usr/local/include and /usr/local/lib).
Use your favourite cpan client to install Lab::Zhinst.

Non-root installation in home directory

you will need something like e.g. local::lib, plenv or perlbrew.

Add the directory which contains the shared library to the LIBRARY_PATH and LD_LIBRARY_PATH environment variables and add the directory which contains the header ziAPI.h to the CPATH environment variable.

You can then install Lab::Zhinst with your favourite cpan client.

See our Travis CI build file for the exact list of needed commands.

Windows

For StrawberryPerl, version 5.26 or newer is required. Especially with 64-bit StrawberryPerl it is currently not possible to use earlier versions (see https://rt.cpan.org/Public/Bug/Display.html?id=121219).
Download and install the LabOne API for Windows (MSI installer).
Make sure that the library directory C:\Program Files\Zurich Instruments\LabOne\API\C\lib is included in the PATH environment variable. Otherwise loading the dynamic library Zhinst.xs.dll will fail.
Use your favourite cpan client to install Lab::Zhinst.

API CONSIDERATIONS

The API provided by this module is basically a one-one mapping of the LabOne C API to Perl5.

For full semantics of the various library functions, we refer to the LabOne manual.

Object orientation

Most ziAPI functions receive a ZIConnection as their first argument. The Init method of this library will create a ZIConnection object and bless it into the Lab::Zhinst class. Most library functions are then called on this Lab::Zhinst object.

Return values and error handling

Most ziAPI functions return an error code. The Perl functions return lists, where the first element is the error code:

my ($error_code, $first_return_value, $second_return_value) = $connection->foobar(@arguments);

The return values are only valid if $error_code is 0.

FUNCTIONS/METHODS

All non-methods are exported by default.

Connecting to Data Server

Init

my ($rv, $connection) = Lab::Zhinst->Init();

Return Lab::Zhinst object. Automatically call ziAPIDestroy on $connection when it goes out of scope.

Connect

my ($rv) = $connection->Connect($hostname, $port);

Disconnect

my ($rv) = $connection->Disconnect();

ziAPIListImplementations

my ($rv, $implementations) = ziAPIListImplementations();

GetConnectionAPILevel

my ($rv, $level) = $connection->GetConnectionAPILevel();

Tree

ListNodes

my ($rv, $nodes) = $connection->ListNodes($path, $bufferSize, $flags);

$flags has to be bitwise or of ZI_LIST_NODES_NONE, ZI_LIST_NODES_RECURSIVE, ZI_LIST_NODES_ABSOLUTE, ZI_LIST_NODES_LEAFSONLY, ZI_LIST_NODES_SETTINGSONLY.

Set and Get Parameters

GetValueD

my ($rv, $double) = $connection->GetValueD($path);

GetValueI

my ($rv, $integer) = $connection->GetValueI($path);

GetDemodSample

my ($rv, $hash_ref) = $connection->GetDemodSample($path);
# keys: timeStamp, x, y, frequency, phase, dioBits, trigger, auxIn0, auxIn1

GetDIOSample

my ($rv, $hash_ref) = $connection->GetDIOSample($path);
# keys: timeStamp, bits, reserved

GetAuxInSample

my ($rv, $hash_ref) = $connection->GetAuxInSample($path);
# keys: timeStamp, ch0, ch1

GetValueB

my ($rv, $byte_string) = $connection->GetValueB($path, $bufferSize);

SetValueD

my ($rv) = $connection->SetValueD($path, $double);

SetValueI

my ($rv) = $connection->SetValueI($path, $integer);

SetValueB

my ($rv) = $connection->SetValueB($path, $byte_string);

SyncSetValueD

my ($rv, $set_value) = $connection->SyncSetValueD($path, $double);

SyncSetValueI

my ($rv, $set_value) = $connection->SyncSetValueI($path, $integer);

SyncSetValueB

my ($rv, $set_value) = $connection->SyncSetValueB($path, $byte_array);

Sync

my ($rv) = $connection->Sync();

EchoDevice

my ($rv) = $connection->EchoDevice($device_serial);

Data Streaming

ziAPIAllocateEventEx

my ($event) = ziAPIAllocateEventEx();

Return Lab::Zhinst::ZIEvent object or undef on error.

ziAPIDeallocateEventEx will be called on $event when it goes out of scope.

my ($rv) = $connection->Subscribe($path);

UnSubscribe

my ($rv) = $connection->UnSubscribe($path);

PollDataEx

my ($rv, $data) = $connection->PollDataEx($event, $timeout_milliseconds);

$data holds a hashref representing a 'struct ZIEvent'. It has the following structure:

$data = {
    valueType => $valueType,
    count     => $count,
    path      => $path,
    values    => [@values],
};

For scalar data like ZIDoubleData, the elements of @values are scalars. For Samples (Demod, AuxIn, DIO, Impedance, ...) the elements are hashrefs.

GetValueAsPollData

my ($rv) = $connection->GetValueAsPollData($path);

Error Handling and Logging in the LabOne C API

ziAPIGetError

my ($rv, $error_string) = ziAPIGetError($result);

GetLastError

my ($rv, $error_string) = $connection->GetLastError($bufferSize);

ziAPISetDebugLevel

ziAPISetDebugLevel($level);

ziAPIWriteDebugLog

ziAPIWriteDebugLog($level, $message);

Device discovery

DiscoveryFind

my ($rv, $device_id) = $connection->DiscoveryFind($device_address);

DiscoveryGet

my ($rv, $json) = $connection->DiscoveryGet($device_id);

REPORTING BUGS

Please report bugs at https://github.com/lab-measurement/Lab-Zhinst/issues.

CONTACT

Feel free to contact us at

The #labmeasurement channel on Freenode IRC.
Our mailing list.

AUTHOR

Simon Reinhardt, <simon.reinhardt@stud.uni-regensburg.de>

COPYRIGHT AND LICENSE

The following license only covers the perl front end to LabOne. LabOne uses different licensing terms, and needs to be installed separately by the user.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.0 or, at your option, any later version of Perl 5 you may have available.

To install Lab::Zhinst, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Lab::Zhinst

CPAN shell

perl -MCPAN -e shell
install Lab::Zhinst

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)