path: root/libvxi11client/perlbits/Client.pm

package VXI11::Client;

use 5.014002;
use strict;
use warnings;

require Exporter;

our @ISA = qw(Exporter);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration	use VXI11::Client ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'all' => [ qw(
	
) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw(
	vxi_startinterruptserver
	vxi_stopinterruptserver
 	vxi_open
	vxi_wait_for_interrupt	
);

our $VERSION = '0.01';

require XSLoader;
XSLoader::load('VXI11::Client', $VERSION);

# Preloaded methods go here.


sub vxi_enable_srq {
	return vxi_enable_srq_long($_[0], 1, $_[1]);
}


sub vxi_disable_srq {
	return vxi_enable_srq_long($_[0], 0 , "");
}


sub vxi_wait_for_interrupt {
	my %args = (
                timeout_ms => 250,
                @_
        );

	return vxi_wait_for_interrupt_long ($args{timeout_ms});
}


sub vxi_clear {
        my $self = shift;
	my %args = (
                waitforlock => 0,
                @_
        );
	return vxi_clear_long ($self, $args{waitforlock});
}


sub vxi_local {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_local_long ($self, $args{waitforlock});
}


sub vxi_remote {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_remote_long ($self, $args{waitforlock});
}


sub vxi_trigger {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_trigger_long ($self, $args{waitforlock});
}


sub vxi_lock {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_lock_long ($self, $args{waitforlock});
}


sub vxi_open {
        my %args = (
		address => '127.0.0.1',
		device => 0,
		@_
        );
        return vxi_open_long ($args{address}, $args{device});
}


sub vxi_write {
	my $self = shift;
	my $data = shift;
	my %args = (
		len => -1,
		waitforlock => 0,
		end => 1,
		@_
	);
	return vxi_write_long($self, $data, $args{len}, $args{waitforlock}, $args{end});
}


sub vxi_read {
	my $self = shift;
	my %args = (
                bufferlen => 1024,
                waitforlock => 0,
                termchrset => 0,
		termchr => 0,
		autochomp => 1,
                @_
        );

	my ($bytes, $string, $reason) = vxi_read_long($self, $args{bufferlen}, $args{waitforlock}, $args{termchrset},$args{termchr});

	if (defined($string) && $args{autochomp}) {
		chomp ($string);
	}
	
	return ($bytes, $string, $reason);
}


sub vxi_readstatusbyte {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_readstatusbyte_long ($self, $args{waitforlock});
}


sub vxi_docmd {
        my $self = shift;
        my $cmd = shift;
	my %args = (
                datain => "",
		datainlen => -1,
		dataoutbufferlen => 256,
                waitforlock => 0,
		autochomp => 1,
                @_
        );

        my ($ret, $dataout, $dataoutlen) = vxi_docmd_long($self, $args{datain}, $args{datainlen}, $args{dataoutbufferlen}, $args{waitforlock});

        if (defined($dataout) && $args{autochomp}) {
                chomp ($dataout);
        }

        return ($ret, $dataout);
}

1;
__END__
# Below is stub documentation for your module. You'd better edit it!

=head1 NAME

VXI11::Client - Perl extension for interfacing with VXI-11 networked instruments

=head1 SYNOPSIS

  use VXI11::Client;

  vxi_startinterruptserver();

  my $instr = vxi_open(address => "192.168.0.62");

  $instr->vxi_lock();
  $instr->vxi_write("*idn?");
  my ($bytes, $buff, $reason) = $instr->vxi_read();
  print "got " . $bytes . ";" . $buff . " reason " . $reason ."\n";

  my ($error, $statusbyte) = $instr->vxi_readstatusbyte();
  printf "status byte is " . $statusbyte . "\n";

  $instr->vxi_create_intr_chan();
  $instr->vxi_enable_srq("myhandle");
  vxi_wait_for_interrupt();
  $instr->vxi_disable_srq();
  $instr->vxi_destroy_intr_chan();
  $instr->vxi_abort();
  $instr->vxi_clear();
  $instr->vxi_trigger();
  $instr->vxi_local();
  $instr->vxi_remote();
  $instr->vxi_unlock();

  $instr->vxi_close();

  vxi_stopinterruptserver();


=head1 SAMPLE SCRIPT

  #!/usr/bin/perl

  use strict;
  use warnings;
  use VXI11::Client;

  # This script tests communications to, and service requests from,
  # an Avtech Electrosystems pulse generator (or any other instrument
  # that accepts the "freq" command).

  my $ip_addr = "192.168.0.62";          # IP address of the instrument,
                                         # or VXI-to-GPIB gateway device.
  my $device = 0;                        # Only revelant if a VXI-to-GPIB
                                         # gateway is used.

  vxi_startinterruptserver();            # Launch a server to handle
                                         # interrupts from the instrument.
  my $my_interrupt_handle = "Avtech";    # Each interrupt source needs a name.

  my $instr = vxi_open( address => $ip_addr, device => $device );

  if ( $instr->vxi_lock() > 0 ) {
      print "Instrument is locked for our use.\n";

      $instr->vxi_remote();              # Lock out the front panel (optional)

      $instr->vxi_clear();               # Reset the device interface.
      $instr->vxi_write("*rst");         # Load default settings.
      $instr->vxi_write("*cls");         # Clear the error queue.

      $instr->vxi_write("*idn?");
      my ( $bytes, $idn, $reason ) = $instr->vxi_read();
      printf "Name of device: $idn\n";

      $instr->vxi_write("*ese 60");      # Flag command-related errors.
      $instr->vxi_write("*sre 32");      # Request service on those errors.
      $instr->vxi_create_intr_chan();    # Create interrupt channel.
      $instr->vxi_enable_srq($my_interrupt_handle);
                                         # Enable service requests on the
                                         # interrupt channel
  }
  else {
      die "We could not obtain a lock.\n";
  }

  # Generate a list of test frequencies
  my @list;
  foreach my $suffix ( "Hz", "kHz", "MHz" ) {
      foreach my $step ( 1, 10, 100 ) {
          foreach my $base ( 1, 2, 5 ) {
              my $freq = ( $base * $step ) . " " . $suffix;
              push @list, $freq;
          }
      }
  }

  # Go up the list, then down again, to ensure that the
  # error system resets properly.
  push @list, reverse(@list);

  # Execute each frequency and see if any errors occur.
  foreach my $freq (@list) {

      print "\nTrying $freq.\n";
      $instr->vxi_write("freq $freq");

      # You could just call "syst:err?" to check for errors after
      # each freq command, eliminating the need for the interrupt channel.
      # That's up to you!

      # Was an interrupt fired within the default wait period of 250 ms?
      my $handle;
      if (   ( $handle = vxi_wait_for_interrupt() )
          && ( $handle eq $my_interrupt_handle ) )
      {
          my ( $error, $statusbyte ) = $instr->vxi_readstatusbyte();
          printf( "Status byte: 0x%x\n", $statusbyte );

          my $response = "";
          until ( $response =~ /No error/i ) {
              $instr->vxi_write("syst:err?");
              ( my $bytes, $response, my $reason ) = $instr->vxi_read();
              if ( $response !~ /No error/i ) {
                  print "Error message: $response\n";
              }
          }

          # clear the error reporting bits
          $instr->vxi_write("*cls");
      }
  }

  # These functions are also available, but aren't especially useful
  # with the Avtech Electrosystems pulse generator.
  $instr->vxi_abort();
  $instr->vxi_trigger();

  # Tidy up!
  $instr->vxi_disable_srq();
  $instr->vxi_destroy_intr_chan();
  $instr->vxi_unlock();
  $instr->vxi_local();
  $instr->vxi_close();


=head1 DESCRIPTION

A client for VXI-11 networked instruments. To start talking to an instrument
call open with the host you want to connect to (ip or hostname) and whether
you want to lock it right away. You can then call the object methods to 
do stuff. For interrupts to work you must call vxi_startinterruptserver before
enabling interrupts. You only need to do this once even if you have multiple
instruments. VXI-11 has mixed client and server roles (with interrupts the client
becomes the server). Starting the interrupt server creates an RPC server on the 
client that the instruments can connect to.

Return codes work like this;
1   - is a success
0   - means the request failed locally, the state inside the client is
incorrect, i.e. calling to enable interrupts before creating the channel
or that the server couldn't be contacted
< 0 - Any negative value is the negated VXI-11 error code from the server

The only exceptions to this are the read and write methods
0   - Error as above or zero bytes read/written
> 0 - Number of bytes read/written

=head2 EXPORT

vxi_startinterruptserver
vxi_stopinterruptserver
vxi_open
vxi_wait_for_interrupt

=head1 SEE ALSO

The vxi-11 spec.

=head1 AUTHOR

daniel, E<lt>daniel@E<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2013 by daniel

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


=cut