diff options
Diffstat (limited to 'libvxi11client/perlbits/Client.pm')
| -rw-r--r-- | libvxi11client/perlbits/Client.pm | 261 |
1 files changed, 234 insertions, 27 deletions
diff --git a/libvxi11client/perlbits/Client.pm b/libvxi11client/perlbits/Client.pm index 12e8214..5d1a3c4 100644 --- a/libvxi11client/perlbits/Client.pm +++ b/libvxi11client/perlbits/Client.pm @@ -185,6 +185,20 @@ __END__ VXI11::Client - Perl module for interfacing with VXI-11 networked test and measurement equipment +=head1 DOWNLOAD + +=begin html + +Latest release: <a href="http://www.avtechpulse.com/options/vxi/client/VXI11-Client-1_0_0.zip">VXI11-Client-1_0_0.zip</a>. + +=end html + +Once unzipped, use the standard perl module install sequence: + + perl Makefile.PL + make + sudo make install + =head1 SYNOPSIS use VXI11::Client; @@ -220,16 +234,124 @@ VXI11::Client - Perl module for interfacing with VXI-11 networked test and measu =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. +=begin html + +VXI11::Client implements a client for VXI-11 networked instruments. +This module was developed to support +<a href="http://www.avtechpulse.com/">Avtech Electrosystems</a> +pulse generators with the +<a href="http://www.avtechpulse.com/options/vxi/">-VXI option</a>, +as well as VXI-11.3 instrumentation from other manufacturers (oscilloscopes, etc). + +=end html + +=head2 BASIC I/O + +A VXI11 connection to an instrument involves establishing a link with up to three +"channels" - core (for normal reads and writes), abort (for cancelling commands), +and interrupt (for receiving instrument-initiated messages and errors). + +Most communication happens using the core channel. To send a query to an instrument, +you need to open the instrument and then call the vxi_write and vxi_read methods +on the returned instrument object: + + $instr = vxi_open( address => "192.168.0.62" ) or die; + $instr->vxi_write("*idn?"); + ( $bytes, $idn, $reason ) = $instr->vxi_read(); + print "This instrument is: $idn\n"; + $instr->vxi_close(); + +=head2 ABORT CHANNEL + +The abort channel is occasionally used, depending on the capabilities of the +instrument. To signal an abort, simply call: + + $instr->vxi_abort(); + +The abort channel is automatically created with the core channel during a +vxi_open. + +=head2 INTERRUPT CHANNEL + +The interrupt channel can be used to watch for error conditions and to +signal service requests. Alternatively, you can manually check for errors +and service requests by polling the error queue or the status byte. If you wish +to use the interrupt channel, your computer must be running an RPC port mapper +service. (On Fedora Linux, this is provided by rpcbind.) Then, you must start +the global (rather than per-object) interrupt listener provided by this module: + + vxi_startinterruptserver(); + +This listener can serve multiple instrument objects. If you wish to use an +instrument's interrupt channel, you must start it after launching the +listener: + + $instr->vxi_create_intr_chan(); + +In contrast to the core and abort channels, the interrupt channel is not +automatically created by vxi_open. + +To receive service requests on this channel, do: + + $instr->vxi_enable_srq("myhandle"); + +The "myhandle" identifier must be unique for each object, so that the global +listener can deliver interrupts to the right object. + +At this point, you may need to send additional commands (based on the +IEEE-488.2 standard, usually) using vxi_write to enable service request +generation within your instrument. These are typical: + + $instr->vxi_write("*ese 60"); # Flag command-related errors. + $instr->vxi_write("*sre 48"); # Request service when they occur. + +When you are expecting the possibility of an interrupt, you watch for the +interrupt using: + + $handle = vxi_wait_for_interrupt() + +If the returned handle is the same as the identifier set above, then an +interrupt been signalled in your instrument. The wait period is 250 ms +by default, but it may be set to a different value. + +The interrupts can be shut down using: + + $instr->vxi_disable_srq(); # local to your instrument + $instr->vxi_destroy_intr_chan(); # local to your instrument + vxi_startinterruptserver(); # affects all instruments + +Use of the interrupt channel is optional. Simpler applications can +omit it, and rely on explicit status checks of the instrument. To +check the status byte (STB), you can use: + + my ($error, $statusbyte) = $instr->vxi_readstatusbyte(); + +To check the error queue, you can use poll it using something like this: + + my $resp = ""; + until ($resp =~ /No error/) { + $instr->vxi_write("syst:err?"); + (my $bytes, $resp, my $reason) = $instr->vxi_read(); + if ($resp !~ /No error/) { + print "ERR: $resp\n"; + } + } + +=head2 LOCKS + +VXI instruments will support more than one VXI link, normally. However, +links can be locked to prevent other links from controlling the +instrument, using: + + $instr->vxi_lock(); # My link shall rule all! + $instr->vxi_unlock(); # Someone else's turn. + +Some functions have an waitforlock optional parameter. If not zero, +this requests that the instrument execute the function later if a lock +is conflicting with execution. The exact nature of this scheme will +be device-dependent. -=head2 USAGE +=head1 USAGE =over @@ -251,8 +373,8 @@ the object methods below. =item $retcode = $instr->vxi_close(); -Destroy the link to the insturment and destroy the local RPC client. -You must not use an instance created with vxi_open(); after calling this. +Destroy the link to the instrument and destroy the local RPC client. +You must not use an instance created with vxi_open after calling this. =item $retcode = $instr->vxi_lock([waitforlock => 'false']); @@ -274,16 +396,19 @@ to provide a length. You can wait for the lock to be freed by via waitforlock. Read some data from the instrument. The default parameters should be fine for most cases. If you need to read more than 1024 bytes you should pass -in the required buffer size via bufferlen. This function will not read more -than the buffer size. The number of bytes returned is what the instrument sent -not what was copied into the buffer. So if the number of bytes returned is +the required buffer size via bufferlen. This function will not read more +than the buffer size. The number of bytes returned is what the instrument sent, +not what was copied into the buffer. If the number of bytes returned is larger than bufferlen the data is truncated. If autochomp is set the newline from the returned data will be automatically removed. =item ($retcode, $dataout, $dataoutlen) = vxi_docmd (INT cmd, [ datain => "", datainlen => -1, dataoutbufferlen => 256, waitforlock => 0, autochomp => 1]); -Send a command to the instrument possibly with some data. The rules for write apply -to datain and the rules for read apply for dataout. +Send a command to the instrument possibly with some data. The rules for write +apply to datain and the rules for read apply for dataout. + +The docmd message is not implemented in VXI-11.3 instruments - it always +an error. You probably need vxi_write instead. =item $retcode = $instr->vxi_abort(); @@ -303,12 +428,12 @@ This must be called after vxi_startinterruptserver. Tell the instrument to fire interrupts/service requests to the interrupt channel. Must be called after vxi_create_intr_chan(). You should give a unique channel handle for each instrument as -you will need this to work out which device set an interrupt/service -request. +you will need this to determine which device sent an interrupt / +service request. =item $retcode = $instr->vxi_disable_srq(); -Tell the instrument that you don't want it to send interrupts/ +Tell the instrument that you don't want it to send interrupts / service requests anymore. This does not destroy the interrupt channel. @@ -329,6 +454,7 @@ an interrupt is caught (could block forever!). =item $retcode = $instr->vxi_remote([waitforlock => 0]); Lock out the instrument's local controls (typically the front panel). +(This is not the same as a link lock implemented by vxi_lock.) =item $retcode = $instr->vxi_local([waitforlock => 0]); @@ -336,7 +462,7 @@ Unlock the instrument's local controls. =item $retcode = $instr->vxi_clear([waitforlock => 0]); -Clear the instrument's display. +Clear the instrument's messaging interface. =item $retcode = $instr->vxi_trigger([waitforlock => 0]); @@ -376,6 +502,77 @@ The only exceptions to this are the read and write methods: print "This instrument is: $idn\n"; $instr->vxi_close(); +=head2 SIMPLE INTERACTIVE CLIENT + + #!/usr/bin/perl + use strict; + use warnings; + use VXI11::Client; + + # This script provides a simple line-based shell for communicating with + # a VXI-11.3 instrument. Errors and responses to queries are signaled to + # this script by polling the instrument status byte. Tested with an + # Avtech Electrosystems pulse generator. + + 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. + + $SIG{INT} = 'graceful_end'; # end on Ctrl+C + + print "\nTrying to establish link with $ip_addr..."; + + my $instr = vxi_open( address => $ip_addr, device => $device ) + or die "Could not open instrument at $ip_addr."; + + my $prompt = "\n> "; + print " OK\nType your commands. Ctrl+C to exit\n" . $prompt; + + $instr->vxi_write("*ese 60"); # Flag command-related errors. + $instr->vxi_write("*sre 48"); # Request service when a response is + # available, or an error has occurred. + + while (1) { + + # check for user input + if ( defined( my $line = <STDIN> ) ) { + $instr->vxi_write($line); + } + + my ( $error, $statusbyte ) = $instr->vxi_readstatusbyte(); + + # query-response message available according to status byte + if ( $statusbyte | 0x10 ) { + my ( $bytes, $response, $reason ) = $instr->vxi_read(); + print $response. "\n"; + } + + # error occurred according to status byte + if ( $statusbyte | 0x20 ) { + my $response = ""; + + # cycle through all errors in the error queue + 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"); + } + print $prompt; + } + + sub graceful_end { + print "\nExiting\n"; + $instr->vxi_close(); + die; + } + =head2 INTERACTIVE CLIENT USING INTERRUPT CHANNEL #!/usr/bin/perl @@ -384,7 +581,7 @@ The only exceptions to this are the read and write methods: use VXI11::Client; # This script provides a simple line-based shell for communicating with - # a VXI-11.3 instrument. Errors and esponses to queries are signaled to + # a VXI-11.3 instrument. Errors and responses to queries are signaled to # this script using the interrupt channel. The rpcbind/portmapper service # must be running on your system for this to work. If not, see the # sample script that does not use the interrupt channel. Tested with an @@ -395,6 +592,8 @@ The only exceptions to this are the read and write methods: my $device = 0; # Only revelant if a VXI-to-GPIB # gateway is used. + $SIG{INT} = 'graceful_end'; # end on Ctrl+C + vxi_startinterruptserver(); # Launch a server to handle # interrupts from the instrument. my $my_interrupt_handle = "Avtech"; # Each interrupt source needs a name. @@ -403,6 +602,10 @@ The only exceptions to this are the read and write methods: my $instr = vxi_open( address => $ip_addr, device => $device ) or die "Could not open instrument at $ip_addr."; + # keep other users away + $instr->vxi_remote(); # no other VXI users + $instr->vxi_lock(); # no front-panel users + my $prompt = "\n> "; print " OK\nType your commands. Ctrl+C to exit\n" . $prompt; @@ -454,12 +657,16 @@ The only exceptions to this are the read and write methods: print $prompt; } - # Tidy up! - $instr->vxi_disable_srq(); - $instr->vxi_destroy_intr_chan(); - $instr->vxi_unlock(); - $instr->vxi_local(); - $instr->vxi_close(); + sub graceful_end { + print "\nExiting\n"; + $instr->vxi_disable_srq(); + $instr->vxi_destroy_intr_chan(); + $instr->vxi_unlock(); + $instr->vxi_local(); + $instr->vxi_close(); + vxi_stopinterruptserver(); + die; + } =head1 SEE ALSO |