/ 
Lab-Measurement-3.803
River stage zero No dependents
/ Lab::Bus::USBtmc

NAME

Lab::Bus::USBtmc - USBtmc (Test & Measurement) Linux kernel driver bus

VERSION

version 3.803

SYNOPSIS

This is the USB TMC (Test & Measurement Class) bus class.

my $tmc = new Lab::Bus::USBtmc({ });

or implicit through instrument and connection creation:

my $instrument = new Lab::Instrument::HP34401A({
  connection_type => 'USBtmc',
  tmc_address=>1,
}

DESCRIPTION

Driver for the interface provided by the usbtmc linux kernel module.

Obviously, this will work for Linux systems only. On Windows, please use Lab::Bus::VISA. The interfaces are (errr, will be) identical.

Note: you don't need to explicitly handle bus objects. The Instruments will create them themselves, and existing bus will be automagically reused.

CONSTRUCTOR

new

my $bus = Lab::Bus::USBtmc({
 });

Return blessed $self, with @_ accessible through $self->config().

Thrown Exceptions

Lab::Bus::USBtmc throws

Lab::Exception::TMCOpenFileError

Lab::Exception::CorruptParameter

Lab::Exception::DriverError

Lab::Exception::Timeout

METHODS

connection_new

$tmc->connection_new({ tmc_address => $addr });

Creates a new connection ("instrument handle") for this bus. The argument is a hash, whose contents depend on the bus type.

For TMC there are several ways to indicate which device is to be used

if more than one is given, it is the first one that is used: tmc_address => $addr selects /dev/usbtmc$addr visa_name=> 'USB::0xVVVV::0xPPPP::SSSSSS::INSTR'; where VVVV is the hex usb vendor number, PPPP is the hex usb product number, and SSSSSS is the serial number string. If SSSSSS is '*', then the first device found that matches vendor and product will be used. usb_vendor=>'0xVVVV' or 0xVVVV vendor number usb_product=>'0xPPPP' or 0xPPPP product number usb_serial=>'SSSSSS' or '*' serial number, or wildcard.

The usb_serial defaults to '*' if not specified.

The handle is usually stored in an instrument object and given to connection_read, connection_write etc. to identify and handle the calling instrument:

$InstrumentHandle = $tmc->connection_new({ usb_vendor => 0x0699, usb_product => 0x1234 });
$result = $tmc->connection_read($self->InstrumentHandle(), { options });

Please note that, because of obscure Linux device configuration issues, it is sometimes difficult to extract the USBtmc device serial number without 'root' privileges. This code tries several techniques, including invoking 'lsusb', looking in /proc/bus/usb, and looking in /sys/kernel/debug/usb/devices. There is no guarantee that those hacking on the Linux kernel won't change these in future.

Also the current (as of kernel 4.7.4, and many earlier versions) default kernel modules for usbtmc has a 'built in' read timeout hardcoded to 5 seconds. The read/timeout code here works with this.

Some years ago, when the USBtmc module was first being added to standard distributions, it was "edited to conform with kernel module style guidelines" which resulted in a completely nonfunctional driver. Alternate (older) versions from device manufacturers DID work, and had greater functionality. If you are using one of those modules, check to see if the timeout logic here requires modification.

Unfortunately, it's not so easy for a little perl module to tell what variety of kernel module is being used, so that will be up to the user.

See Lab::Instrument::Read().

connection_write

$tmc->connection_write( $InstrumentHandle, { command => $Command } );

Sends $Command to the instrument specified by the handle.

connection_read

$tmc->connection_read( $InstrumentHandle, { read_length => $readlength } );

Reads back a maximum of $readlength bytes. If $readlength <= 0 (which is the default) there is no limit.

Setting Brutal to a true value will result in timeouts being ignored, and the gathered data returned without error.

IF there is a timeout (i.e., no data) then connection_read returns a zero length string.

timeout

$tmc->timeout( $connection_handle, $timeout );

Sets the timeout in seconds for tmc operations on the device/connection specified by $connection_handle. $timeout <= 0 means "no timeout, indefinate wait".

The timeout is quantized in units of the kernel module timeout (currently 5 sec in kernel 4.7.4), so the timeout just results in determining the number of reads that are attempted before a timeout error is thrown.

config

Provides unified access to the fields in initial @_ to all the child classes. E.g.

$tmc_serial = $instrument->config(usb_serial);

Without arguments, returns a reference to the complete $self->config aka @_ of the constructor.

$config = $bus->config();
$tmc_serial = $bus->config()->{'usb_serial'};

get_stb

$statusbyte = $tmc->get_stb($connection_handle, [$stbmask]);

reads the STB register, using ioctl/USB interrupt endpoint, so it does not disturb the command/data queues. If a stbmask is provided, it is "anded" with the status byte and returns 'true' if any bits are set. $stbmask = 0x10 is the MAV bit for 'more data available'.

CAVEATS/BUGS

Lots, I'm sure.

SEE ALSO

COPYRIGHT AND LICENSE

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

Copyright 2012       Hermann Kraus
          2016       Charles Lane, Simon Reinhardt
          2017       Andreas K. Huettel
          2020       Andreas K. Huettel
          2021       Charles Lane

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