Simon Reinhardt

NAME

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

SYNOPSIS

 use Lab::Zhinst;
 
 ####################################################

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

 # Connect to DataServer at localhost, port 8004.
 my $connection = Lab::Zhinst->new("localhost", 8004);

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

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

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

 my $connection = Lab::Zhinst->new($address, 8004);
 my $device = "/dev3281";
 my $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

  • Make sure that you have a 32-bit version of StrawberryPerl 5.20 or 5.18. It is currently not possible to use other 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 of our 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.

The following features have been added to make the interface more Perlish:

Object Orientation

Most ziAPI functions receive a ZIConnection as their first argument. The new 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.

Error Handling

Most ziAPI functions return an error code. This library checks the return values from the ziAPI functions and calls Carp's croak function on error.

Automatic Memory Allocation

Some ziAPI functions, like ziAPIListNodes, require a user provided buffer for their output. The function will return an error if the provided buffer is too small to hold the result. This library will repeatedly reallocate buffers until they have a suitable size.

LabOne API COVERAGE

So far, this module only implements LabOne's core API. The 'data streaming' and 'fast asynchronous operation' API's can be added on request.

EXPORTED FUNCTIONS

ListImplementations

 my $implementations = ListImplementations();

SetDebugLevel

 SetDebugLevel($level);

Allowed levels: 0 (trace), 1 (info), ..., 5 (fatal), 6 (status).

WriteDebugLog

 WriteDebugLog($level, $message);

PROVIDED METHODS

new

 my $connection = Lab::Zhinst->new($dataserver_address, $dataserver_port);

GetConnectionAPILevel

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

ListNodes

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

$flags is bitwise or of ZI_LIST_NODES_NONE, ZI_LIST_NODES_RECURSIVE, ZI_LIST_NODES_ABSOLUTE, ZI_LIST_NODES_LEAFSONLY, ZI_LIST_NODES_SETTINGSONLY.

GetValueD

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

GetValueI

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

GetValueB

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

GetDemodSample

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

GetDIOSample

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

GetAuxInSample

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

SetValueD

 $connection->SetValueD($path, $double);

SetValueI

 $connection->SetValueI($path, $integer);

SetValueB

 $connection->SetValueB($path, $byte_string);

SyncSetValueD

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

SyncSetValueI

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

SyncSetValueB

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

Sync

 $connection->Sync();

EchoDevice

 $connection->EchoDevice($device_serial);

DiscoveryFind

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

DiscoveryGet

 my $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.

SEE ALSO

AUTHOR

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

COPYRIGHT AND LICENSE

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

Copyright (C) 2017 by Simon Reinhardt

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.