View on
MetaCPAN
Simon Reinhardt > Lab-Zhinst > Lab::Zhinst

Download:
Lab-Zhinst-1.02.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 1.02   Source  

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

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

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.

Subscribe

 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

SEE ALSO ^

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.

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.

syntax highlighting: