#DistZilla: +PodWeaver
#PODNAME: Lab::Measurement::Backends
#ABSTRACT: Back end packages (hardware drivers) for Lab::Measurement

__END__

=pod

=encoding UTF-8

=head1 NAME

Lab::Measurement::Backends - Back end packages (hardware drivers) for Lab::Measurement

=head1 VERSION

version 3.931

=head1 National Instruments NI-VISA back-end

The National Instruments NI-VISA library and the associated GPIB drivers are
widely used and proven code for accessing lab devices, and our clear
recommendation for controlling lab devices under Microsoft Windows. For the
respective downloads, please follow the provided links.
Linux support is available, however, installation can be complicated, and there
is no support for USB-GPIB adaptors under Linux. A lot of tips and tricks can
be found at the
L<NI Linux User Forum|http://decibel.ni.com/content/groups/linux-users>. In general,
L<National Instruments|http://sine.ni.com/psp/app/doc/p/id/psp-411"> offers
excellent documentation. We especially recommend the
L<NI-VISA User Manual|http://www.ni.com/pdf/manuals/370423a.pdf>, the
L<NI-VISA Programmer Reference Manual|http://www.ni.com/pdf/manuals/370132c.pdf> these references of
L<VISA resource names|http://zone.ni.com/reference/en-XX/help/371361B-01/lvinstio/visa_resource_name_generic/>
and L<VISA error codes|http://zone.ni.com/reference/en-XX/help/371361B-01/lverror/visa_error_codes/>.

B<< For using the NI VISA library, you will have to also install our separate Perl
package L<Lab::VISA> providing the Perl language bindings. Detailed
L<installation instructions|Lab::VISA::Installation> are provided in that
package. >>

=head1 Linux-GPIB back-end

The L<Linux-GPIB project|http://linux-gpib.sourceforge.net/>  aims at
providing free and open-source hardware drivers and a GPIB library with an API
compatible to the NI drivers (without VISA). The package code is considered
stable and feature-complete; new releases occur mainly as response to changes
in the kernel driver interface.

=head2 Installing Linux-GPIB

Note that on Gentoo Linux-GPIB is packaged. On distros where this is not the
case, you can use the following steps. For more details, consult Linux-GPIB's
F<INSTALL> file. This guide was tested on Debian 11 with Linux-GPIB versions 4.3.4.

=over

=item * Install the kernel headers, gcc and make. On Debian you can run
this command:

 root # apt-get install linux-headers-`uname -r` build-essential

=item * Download the
L<Linux-GPIB sources|http://sourceforge.net/projects/linux-gpib/files/>
 and build with the usual procedure:

 user $ tar -xf linux-gpib-4.3.4.tar.gz

Inside of this download folder you will find two more archives, the kernel drivers as well as the user drivers. Untar those as well and navigate inside of the kernel forlder first.

 user $ tar -xf linux-gpib-kernel-4.3.4.tar.gz
 user $ tar -xf linux-gpib-user-4.3.4.tar.gz
 user $ cd linux-gpib-kernel-4.3.4
 user $ ./configure
 user $ make

install the library and kernel drivers as root:

 root # make install

now navigate to the linux-gpib-user-4.3.4 directory. 

 user $ cd .. && cd linux-gpib-user-4.3.4
 user $ ./configure --sysconfdir=/etc
 user $ make
 root # make install

Setting C<--sysconfdir=/etc> will ensure that proper udev rules are installed
into C</etc/udev/rules.d/> which are required to automatically configure
NI-USB-GPIB adapters. Also, the rules will give users in the B<gpib>
group have proper permission to use the gpib boards.

By default the shared lib F<linuxgpib.so> is installed into
C</usr/local/lib/>. If this is not part of the system's shared library search
path, add C</usr/local/lib> to F</et/ld.so.conf> and run C<ldconfig> as root.

=item * Stay inside of the linux-gpib-user-4.3.4 directory and install the Perl bindings:

 root # cpanm ./language/perl

if you are using plenv or don't use the standard Perl installation be sure to execute the cpanm command with the user profile and NOT as the root user:

 user $ cpanm ./language/perl

=item * Add your user to the gpib group.

 root # adduser user gpib

to create a new user group use

 root # groupadd gpib

=item * Troubleshooting

In case you are getting an error message like

 user $ libgpib.so.0: cannot open shared object file: No such file or directory

check if the kernel headers are installed properly. Try running

 user $ sudo apt-get install linux-headers-$(uname -r)

again, consider adding your kernel version manually. The latest kernel can be found under F</lib/modules>. Furthermore, running

 user $ sudo ldconfig

and a reboot can work some magic.

=back

=head2 Example Configuration for the GPIB-USB-HS controller

NI's L<GPIB-USB-HS|http://sine.ni.com/nips/cds/view/p/lang/de/nid/201586> is supported out of the box by Linux-GPIB without any
additional proprietary firmware.

You need a configuration file F</etc/gpib.conf>:

 interface {
        minor = 0       /* board index, minor = 0 uses /dev/gpib0, minor = 1 uses /dev/gpib1, etc. */
        board_type = "ni_usb_b" /* type of interface board being used */
        pad = 0 /* primary address of interface             */
        sad = 0 /* secondary address of interface           */
        timeout = T3s   /* timeout for commands */

        eos = 0x0a      /* EOS Byte, 0xa is newline and 0xd is carriage return */
        set-reos = yes  /* Terminate read if EOS */
        set-bin = no    /* Compare EOS 8-bit */
        set-xeos = no   /* Assert EOI whenever EOS byte is sent */
        set-eot = yes   /* Assert EOI with last byte on writes */

 /* settings for boards that lack plug-n-play capability */
        base = 0        /* Base io ADDRESS                  */
        irq  = 0        /* Interrupt request level */
        dma  = 0        /* DMA channel (zero disables)      */


        master = yes    /* interface board is system controller */
 }

Now, you can use the interactive C<ibtest> and C<ibterm> programs to test the installation.

=head1 Zurich Instruments LabOne

Lab::Measurement provides initial support for devices from Zurich
Instruments. These can be used on both Linux and Windows. This requires that
the LabOne API, provided by the vendor, is installed on the measurement
PC. Moreover, you need the Perl module L<Lab::Zhinst>, which
provides the Perl bindings to the LabOne API. The Lab::Zhinst documentation
covers all steps of the installation.

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by the Lab::Measurement team; in detail:

  Copyright 2016       Simon Reinhardt
            2017       Andreas K. Huettel, Simon Reinhardt
            2021       Fabian Weinelt, Simon Reinhardt


This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut