blib/lib/USB/TMC.pm

filter: Statementstmt 77.7% 7 / 9 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 83.3% 10 / 12 CC 1 SCAR 0.9
CC
1
Cov
78%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
↑ Summary
1  
2 =head1 NAME
3  
4 USB::TMC - Perl interface to USB Test & Measurement (USBTMC) backend.
5  
6 =head1 SYNOPSIS
7  
8 use USB::TMC;
9  
10 # Open usb connection to Agilent 34410A digital multimeter
11 my $usbtmc = USB::TMC->new(
12 vid => 0x0957,
13 pid => 0x0607,
14 serial => 'MY47000419', # only needed if vid/pid is ambiguous
15 );
16
17 $usbtmc->write(data => "*CLS\n");
18 $usbtmc->write(data => "VOLT:NPLC 10\n");
19  
20 $usbtmc->write(data => ":read?\n");
21 print $usbtmc->read(length => 100);
22 print $usbtmc->query(data => ":read?\n", length => 100);
23
24 my $capabilities = $usbtmc->get_capabilities();
25 my $support_term_char = $capabilities->{support_term_char};
26  
27 =head1 DESCRIPTION
28  
29 This module provides a user-space L<USBTMC|http://www.usb.org/developers/docs/devclass_docs/USBTMC_1_006a.zip> driver.
30  
31 Internally this module is based on L<USB::LibUSB>.
32  
33 Does not yet support the additional features of USBTMC-USB488. But those could
34 easily be added if needed.
35  
36 =head1 INSTALLATION
37  
38 The documentation of L<USB::LibUSB> contains detailed installation
39 instructions.
40  
41 To access USB devices as a non-root user we need udev rules. E.g. on
42 Debian we add a file F</etc/udev/rules.d/97-usbtmc.rules> with contents:
43  
44 ATTR{idVendor}=="0957", GROUP="usbtmc"
45  
46 where "0957" (actually 0x0957) is the USB vendor ID of Agilent Technologies.
47  
48 With this udev rule, all users in the "usbtmc" group can access the device.
49  
50  
51 =head1 METHODS
52  
53 Errors with USB transfers will result in a croak.
54  
55 Use L<default timeout|/new> if C<timeout> arg is not given.
56  
57 =cut
58  
59 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
60 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
61  
62 package USB::TMC;
63 $USB::TMC::VERSION = '0.009';
64 0 ▶use USB::LibUSB;
Subroutine BEGIN: called CC=1 SCAR=2.6
65 use Moose;
66 use MooseX::Params::Validate 'validated_list';
67 use Carp;
68 use Data::Dumper 'Dumper';
69  
70 use constant {
71 MSGID_DEV_DEP_MSG_OUT => 1,
72 MSGID_REQUEST_DEV_DEP_MSG_IN => 2,
73 MSGID_DEV_DEP_MSG_IN => 2,
74 MSGID_VENDOR_SPECIFIC_OUT => 126,
75 MSGID_REQUEST_VENDOR_SPECIFIC_IN => 127,
76 MSGID_VENDOR_SPECIFIC_IN => 127,
77  
78 MESSAGE_FINALIZES_TRANSFER => "\x{01}",
79 MESSAGE_DOES_NOT_FINALIZE_TRANSFER => "\x{00}",
80  
81 FEATURE_SELECTOR_ENDPOINT_HALT => 0,
82  
83 BULK_HEADER_LENGTH => 12,
84  
85 # bRequest values
86 INITIATE_ABORT_BULK_OUT => 1,
87 CHECK_ABORT_BULK_OUT_STATUS => 2,
88 INITIATE_ABORT_BULK_IN => 3,
89 CHECK_ABORT_BULK_IN_STATUS => 4,
90 INITIATE_CLEAR => 5,
91 CHECK_CLEAR_STATUS => 6,
92 GET_CAPABILITIES => 7,
93  
94 # status values
95 STATUS_SUCCESS => 0x01,
96 STATUS_PENDING => 0x02,
97 STATUS_FAILED => 0x80,
98  
99 };
100  
101 my $null_byte = "\x{00}";
102  
103 has 'vid' => (
104 is => 'ro',
105 isa => 'Int',
106 required => 1
107 );
108  
109 has 'pid' => (
110 is => 'ro',
111 isa => 'Int',
112 required => 1
113 );
114  
115 has 'serial' => (
116 is => 'ro',
117 isa => 'Str',
118 );
119  
120 has 'ctx' => (
121 is => 'ro',
122 isa => 'USB::LibUSB',
123 init_arg => undef,
124 writer => '_ctx',
125 );
126  
127 has 'device' => (
128 is => 'ro',
129 isa => 'USB::LibUSB::Device',
130 init_arg => undef,
131 writer => '_device',
132 );
133  
134 has 'handle' => (
135 is => 'ro',
136 isa => 'USB::LibUSB::Device::Handle',
137 init_arg => undef,
138 writer => '_handle',
139 );
140  
141 # Bulk endpoint addresses.
142 has 'bulk_out_endpoint' => (
143 is => 'ro',
144 isa => 'Int',
145 init_arg => undef,
146 writer => '_bulk_out_endpoint',
147 );
148  
149 has 'bulk_in_endpoint' => (
150 is => 'ro',
151 isa => 'Int',
152 init_arg => undef,
153 writer => '_bulk_in_endpoint',
154 );
155  
156 has 'btag' => (
157 is => 'ro',
158 isa => 'Int',
159 init_arg => undef,
160 writer => '_btag',
161 default => 0,
162 );
163  
164 has 'reset_device' => (
165 is => 'ro',
166 isa => 'Bool',
167 default => 0,
168 );
169  
170 has 'debug_mode' => (
171 is => 'ro',
172 isa => 'Bool',
173 default => 0
174 );
175  
176 has 'libusb_log_level' => (
177 is => 'ro',
178 isa => 'Int',
179 default => LIBUSB_LOG_LEVEL_WARNING,
180 );
181  
182 has 'term_char' => (
183 is => 'ro',
184 isa => 'Maybe[Str]',
185 default => undef,
186 );
187  
188 has 'interface_number' => (
189 is => 'ro',
190 isa => 'Int',
191 writer => '_interface_number',
192 init_arg => undef,
193  
194 );
195  
196 has 'timeout' => (
197 is => 'rw',
198 isa => 'Num',
199 default => 5,
200 );
201  
202 sub _get_timeout_arg {
203 my $self = shift;
204 my $timeout = shift;
205 if ( not defined $timeout ) {
206 $timeout = $self->timeout();
207 }
208  
209 $timeout = sprintf( "%.0f", $timeout * 1000 );
210 return $timeout;
211 }
212  
213 sub _timeout_arg {
214 return ( timeout => { isa => 'Maybe[Num]', optional => 1 } );
215 }
216  
217 sub _debug {
218 my $self = shift;
219 if ( $self->debug_mode() ) {
220 warn "USBTMC debug: ", @_, "\n";
221 }
222 }
223  
224 =head2 new
225  
226 my $usbtmc = USB::TMC->new(
227 vid => $vid,
228 pid => $pid,
229 serial => $serial, # optional
230 reset_device => 1, # default: do not reset device
231 debug_mode => 1, # print lots of debug messages
232 libusb_log_level => LIBUSB_LOG_LEVEL_DEBUG, # Import LIBUSB_LOG_LEVEL_* constant from USB::LibUSB
233 term_char => "\n", # Stop a read request if the term_char occurs in the
234 # byte stream. Default: do not use term char
235 timeout => 10, # timeout in seconds. default: 5
236 );
237  
238 =cut
239  
240 sub BUILD {
241 my $self = shift;
242  
243 # TermChar valid?
244 my $term_char = $self->term_char();
245 if ( defined $term_char ) {
246 if ( length $term_char != 1 || $term_char =~ /[^[:ascii:]]/ ) {
247 croak "invalid TermChar";
248 }
249 $self->_debug( "Using TermChar ", Dumper $term_char);
250 }
251 else {
252 $self->_debug("Not using TermChar");
253 }
254  
255 my $ctx = USB::LibUSB->init();
256 $ctx->set_debug( $self->libusb_log_level() );
257  
258 my $handle;
259 if ( $self->serial() ) {
260 $handle = $ctx->open_device_with_vid_pid_serial(
261 $self->vid(),
262 $self->pid(), $self->serial()
263 );
264 }
265 else {
266 # Croak if we have multiple devices with the same vid:pid.
267 $handle = $ctx->open_device_with_vid_pid_unique(
268 $self->vid(),
269 $self->pid()
270 );
271 }
272  
273 if ( $self->reset_device() ) {
274 $self->_debug("Doing device reset.");
275 $handle->reset_device();
276 }
277  
278 my $device = $handle->get_device();
279  
280 eval {
281 # This will throw on windows and darwin. Catch exception with eval.
282 $self->_debug("enable auto detach of kernel driver.");
283 $handle->set_auto_detach_kernel_driver(1);
284 };
285  
286 $self->_ctx($ctx);
287 $self->_device($device);
288 $self->_handle($handle);
289  
290 my $usbtmc_interface_number = $self->_find_usbtmc_interface();
291 $self->_interface_number($usbtmc_interface_number);
292  
293 $self->_debug("Claiming interface no. $usbtmc_interface_number");
294 $handle->claim_interface($usbtmc_interface_number);
295  
296 $self->_get_endpoint_addresses();
297  
298 # $self->_debug(
299 # "Request clear_feature endpoint_halt for both bulk endpoints.");
300  
301 # $self->clear();
302 # $self->clear_halt_out();
303 # $self->clear_halt_in();
304 # $self->clear_feature_endpoint_out();
305 # $self->clear_feature_endpoint_in();
306 }
307  
308 sub _find_usbtmc_interface {
309  
310 # Relevant if device has additional non-TMC interfaces.
311 my $self = shift;
312 my $config = $self->device()->get_active_config_descriptor();
313 my @interfaces = @{ $config->{interface} };
314 for my $interface (@interfaces) {
315 if (@{$interface} > 1) {
316 $self->_debug("Interface with multiple alternates?!");
317 }
318 # Assume that we have only one alternate setting
319 $interface = $interface->[0];
320 if ( $interface->{bInterfaceClass} == 0xFE
321 && $interface->{bInterfaceSubClass} == 3 ) {
322 my $number = $interface->{bInterfaceNumber};
323 $self->_debug("Found USBTMC interface at number $number");
324 return $number;
325 }
326 }
327 croak "Did not find a USBTMC interface. Interfaces: ",
328 Dumper \@interfaces;
329 }
330  
331 sub _get_endpoint_addresses {
332 my $self = shift;
333 my $interface_number = $self->interface_number();
334  
335 my $config = $self->device()->get_active_config_descriptor();
336 my $interface = $config->{interface}[$interface_number];
337 $interface = $interface->[0]; # Assume one altenate setting
338 my @endpoints = @{ $interface->{endpoint} };
339  
340 if ( @endpoints != 2 && @endpoints != 3 ) {
341 croak "USBTMC interface needs either 2 or 3 endpoints.";
342 }
343  
344 my ( $bulk_out_address, $bulk_in_address );
345 for my $endpoint (@endpoints) {
346 my $address = $endpoint->{bEndpointAddress};
347 my $direction = $address & LIBUSB_ENDPOINT_DIR_MASK;
348 my $type = $endpoint->{bmAttributes} & LIBUSB_TRANSFER_TYPE_MASK;
349 if ( $type == LIBUSB_TRANSFER_TYPE_BULK ) {
350 if ( $direction == LIBUSB_ENDPOINT_OUT ) {
351 $self->_debug( "Found bulk-out endpoint with address "
352 . sprintf( "0x%x", $address ) );
353 $bulk_out_address = $address;
354 }
355 elsif ( $direction == LIBUSB_ENDPOINT_IN ) {
356 $self->_debug( "Found bulk-in endpoint with address "
357 . sprintf( "0x%x", $address ) );
358 $bulk_in_address = $address;
359 }
360 }
361 }
362  
363 if ( !$bulk_out_address || !$bulk_in_address ) {
364 croak "Did not find all required endpoints.";
365 }
366  
367 $self->_bulk_out_endpoint($bulk_out_address);
368 $self->_bulk_in_endpoint($bulk_in_address);
369 }
370  
371 =head2 write
372  
373 $usbtmc->write(data => $data, timeout => $timeout);
374  
375 Do DEV_DEP_MSG_OUT transfer. So far this only supports USBTMC messages
376 consisting of a single transfer.
377  
378 =cut
379  
380 sub write {
381 my $self = shift;
382 $self->dev_dep_msg_out(@_);
383 }
384  
385 =head2 read
386  
387 my $data = $usbtmc->read(length => $read_length, timeout => $timeout);
388  
389 Do REQUEST_DEV_DEP_MSG_IN and DEV_DEP_MSG_IN transfers.
390  
391 =cut
392  
393 sub read {
394 my $self = shift;
395 my ( $length, $timeout ) = validated_list(
396 \@_,
397 length => { isa => 'Int' },
398 _timeout_arg(),
399 );
400  
401 my $result = '';
402  
403 # Do read requests until EOM flag is set.
404 while ($length) {
405 $self->request_dev_dep_msg_in(
406 length => $length,
407 timeout => $timeout
408 );
409 my ( $data, $eom )
410 = $self->dev_dep_msg_in( length => $length, timeout => $timeout );
411 $result .= $data;
412 $length -= length($data);
413 if ($eom) {
414 last;
415 }
416 }
417 return $result;
418 }
419  
420 sub dev_dep_msg_out {
421 my $self = shift;
422 my ( $data, $timeout ) = validated_list(
423 \@_,
424 data => { isa => 'Str' },
425 _timeout_arg(),
426 );
427  
428 $self->_debug("dev_dep_msg_out with data $data");
429  
430 my $header = $self->_dev_dep_msg_out_header( length => length $data );
431 my $endpoint = $self->bulk_out_endpoint();
432  
433 # Ensure that total number of bytes is multiple of 4.
434 $data .= $null_byte x ( ( 4 - ( length $data ) % 4 ) % 4 );
435 $data = $header . $data;
436  
437 my $transferred = eval {
438 $self->handle()->bulk_transfer_write(
439 $endpoint, $data,
440 $self->_get_timeout_arg($timeout)
441 );
442 };
443 if ($@) {
444 $self->_debug(
445 "dev_dep_msg_out: write failed. Aborting bulk transfer.");
446 $self->abort_bulk_out( timeout => $timeout );
447 croak($@);
448 }
449  
450 my $data_length = length($data);
451 if ( $transferred != $data_length ) {
452 croak
453 "dev_dep_msg_out: data_length = $data_length, transferred = $transferred";
454 }
455 }
456  
457 sub dev_dep_msg_in {
458 my $self = shift;
459 my ( $length, $timeout ) = validated_list(
460 \@_,
461 length => { isa => 'Int' },
462 _timeout_arg(),
463 );
464  
465 $self->_debug("Doing dev_dep_msg_in with length $length");
466  
467 my $endpoint = $self->bulk_in_endpoint();
468 my $data = eval {
469 $self->handle()->bulk_transfer_read(
470 $endpoint, $length + BULK_HEADER_LENGTH
471 , $self->_get_timeout_arg($timeout)
472 );
473 };
474 if ($@) {
475 $self->_debug("dev_dep_msg_in: read failed. Aborting bulk transfer.");
476 $self->abort_bulk_in( timeout => $timeout );
477 croak($@);
478 }
479  
480 if ( length $data < BULK_HEADER_LENGTH ) {
481 croak "dev_dep_msg_in does not contain header";
482 }
483  
484 my $header = substr( $data, 0, BULK_HEADER_LENGTH );
485 my $msg_id = unpack( 'C', substr( $header, 0, 1 ) );
486 my $transfer_attributes = unpack( 'C', substr( $header, 8, 1 ) );
487  
488 if ( $msg_id != MSGID_DEV_DEP_MSG_IN ) {
489 croak "dev_dep_msg_in message with wrong message id '$msg_id'";
490 }
491  
492 my $transfer_size = unpack( 'V', substr( $header, 4, 4 ) );
493 if ( $transfer_size == 0 ) {
494 croak("dev_dep_msg_in: zero transfer size");
495 }
496  
497 # Data may contain trailing alignment bytes!
498 # strip them by returning only $transfer_size bytes.
499 $data = substr( $data, BULK_HEADER_LENGTH, $transfer_size );
500 my $eom = $transfer_attributes & 1;
501 return ( $data, $eom );
502 }
503  
504 sub request_dev_dep_msg_in {
505 my $self = shift;
506 my ( $length, $timeout ) = validated_list(
507 \@_,
508 length => { isa => 'Int', default => 1000 },
509 _timeout_arg(),
510 );
511  
512 $self->_debug("Doing request_dev_dep_msg_in with length $length");
513 my $header = $self->_request_dev_dep_msg_in_header( length => $length );
514 my $endpoint = $self->bulk_out_endpoint();
515  
516 # Length of $header is already multiple of 4.
517 my $transferred = eval {
518 $self->handle()->bulk_transfer_write(
519 $endpoint, $header,
520 $self->_get_timeout_arg($timeout)
521 );
522 };
523 if ($@) {
524 $self->_debug(
525 "request_dev_dep_msg_in: write failed. Aborting bulk transfer.");
526 $self->abort_bulk_out( timeout => $timeout );
527 croak($@);
528 }
529 }
530  
531 sub _dev_dep_msg_out_header {
532 my $self = shift;
533 my ($length) = validated_list( \@_, length => { isa => 'Int' } );
534  
535 my $header = $self->_bulk_out_header( MSGID => MSGID_DEV_DEP_MSG_OUT );
536 $header .= pack( 'V', $length );
537 $header .= MESSAGE_FINALIZES_TRANSFER;
538 $header .= $null_byte x 3; # Reserved bytes.
539 return $header;
540 }
541  
542 sub _request_dev_dep_msg_in_header {
543 my $self = shift;
544 my ($length) = validated_list( \@_, length => { isa => 'Int' } );
545 my $header
546 = $self->_bulk_out_header( MSGID => MSGID_REQUEST_DEV_DEP_MSG_IN );
547  
548 # Transfer length
549 $header .= pack( 'V', $length );
550  
551 my $term_char = $self->term_char();
552 if ( defined $term_char ) {
553 $header .= pack( 'C', 2 );
554 $header .= $term_char;
555 }
556 else {
557 $header .= pack( 'C', 0 );
558 $header .= $null_byte;
559 }
560 $header .= $null_byte x 2; # Reserved. Must be 0x00.
561  
562 return $header;
563 }
564  
565 sub _bulk_out_header {
566 my $self = shift;
567 my ($MSGID) = validated_list( \@_, MSGID => { isa => 'Int' } );
568 my $bulk_out_header = pack( 'C', $MSGID );
569 my ( $btag, $btag_inverse ) = $self->_btags();
570 $bulk_out_header .= $btag . $btag_inverse;
571  
572 $bulk_out_header .= $null_byte; # Reserved. Must be 0x00;
573  
574 return $bulk_out_header;
575 }
576  
577 sub _btags {
578 my $self = shift;
579 my $btag = $self->btag();
580 $btag++;
581 if ( $btag == 256 ) {
582 $btag = 1;
583 }
584 $self->_btag($btag);
585 my $btag_inverse = ( $btag ^ 0xff );
586 return ( pack( 'C', $btag ), pack( 'C', $btag_inverse ) );
587 }
588  
589 #
590 #
591 # USBTMC requests
592 #
593 #
594  
595 sub abort_bulk_out {
596 my $self = shift;
597 my ($timeout) = validated_list(
598 \@_,
599 _timeout_arg()
600 );
601 my $initiate_status
602 = $self->initiate_abort_bulk_out( timeout => $timeout );
603 $initiate_status = unpack( 'C', $initiate_status );
604 if ( $initiate_status != STATUS_SUCCESS ) {
605 carp "INITIATE_ABORT_BULK_OUT failed with status $initiate_status";
606 return;
607 }
608  
609 # Check status
610 while (1) {
611 my $clear_status
612 = $self->check_abort_bulk_out_status( timeout => $timeout );
613 my $status = unpack( 'C', substr( $clear_status, 0, 1 ) );
614 if ( $status == STATUS_PENDING ) {
615 next;
616 }
617 else {
618 if ( $status != STATUS_SUCCESS ) {
619 carp(
620 "CHECK_ABORT_BULK_OUT_STATUS failed with status $status");
621 }
622 $self->clear_feature_endpoint_out( timeout => $timeout );
623 return;
624 }
625 }
626 }
627  
628 sub abort_bulk_in {
629 my $self = shift;
630 my ($timeout) = validated_list(
631 \@_,
632 _timeout_arg()
633 );
634  
635 my $initiate_status
636 = $self->initiate_abort_bulk_in( timeout => $timeout );
637 $initiate_status = unpack( 'C', $initiate_status );
638 if ( $initiate_status != STATUS_SUCCESS ) {
639 carp "INITIATE_ABORT_BULK_IN failed with status $initiate_status";
640 return;
641 }
642  
643 # Check status
644 while (1) {
645 my $clear_status
646 = $self->check_abort_bulk_in_status( timeout => $timeout );
647 my $status = unpack( 'C', substr( $clear_status, 0, 1 ) );
648 my $bmAbortBulkIn = unpack( 'C', substr( $clear_status, 1, 1 ) );
649 if ( $status == STATUS_PENDING ) {
650 $self->_debug(
651 "check_abort_bulk_in_status bmAbortBulkIn = $bmAbortBulkIn\n"
652 );
653  
654 # If bmAbortBulkIn.D0 = 1, the Host should read from the
655 # Bulk-IN endpoint until a short packet is received.
656 if ( $bmAbortBulkIn & 1 ) {
657 my $endpoint = $self->bulk_in_endpoint();
658 my $data = $self->handle()->bulk_transfer_read(
659 $endpoint, 1000,
660 $self->_get_timeout_arg($timeout)
661 );
662 $self->_debug(
663 "check_abort_bulk_in_status read bytes: ",
664 length($data)
665 );
666 }
667 next;
668 }
669 else {
670 if ( $status != STATUS_SUCCESS ) {
671 carp("CHECK_ABORT_BULK_IN_STATUS failed with status $status");
672 }
673 return;
674 }
675 }
676 }
677  
678 sub initiate_abort_bulk_out {
679 my $self = shift;
680 my ($timeout) = validated_list(
681 \@_,
682 _timeout_arg()
683 );
684  
685 $self->_debug("initiate abort bulk out");
686 my $bmRequestType = 0xa2;
687 my $bRequest = INITIATE_ABORT_BULK_OUT;
688 my $wValue = $self->btag();
689 my $wIndex = $self->bulk_out_endpoint();
690 my $wLength = 2;
691 return $self->handle()->control_transfer_read(
692 $bmRequestType, $bRequest, $wValue, $wIndex,
693 $wLength, $self->_get_timeout_arg($timeout)
694 );
695 }
696  
697 sub initiate_abort_bulk_in {
698 my $self = shift;
699 my ($timeout) = validated_list(
700 \@_,
701 _timeout_arg()
702 );
703  
704 $self->_debug("initiate abort bulk in");
705 my $bmRequestType = 0xa2;
706 my $bRequest = INITIATE_ABORT_BULK_IN;
707 my $wValue = $self->btag();
708 my $wIndex = $self->bulk_in_endpoint();
709 my $wLength = 2;
710 return $self->handle()->control_transfer_read(
711 $bmRequestType, $bRequest, $wValue, $wIndex,
712 $wLength, $self->_get_timeout_arg($timeout)
713 );
714 }
715  
716 sub check_abort_bulk_out_status {
717 my $self = shift;
718 my ($timeout) = validated_list( \@_, _timeout_arg() );
719  
720 $self->_debug("check abort bulk out status");
721 my $bmRequestType = 0xa2;
722 my $bRequest = CHECK_ABORT_BULK_OUT_STATUS;
723 my $wValue = 0;
724 my $wIndex = $self->bulk_out_endpoint();
725 my $wLength = 8;
726 return $self->handle()->control_transfer_read(
727 $bmRequestType, $bRequest, $wValue, $wIndex,
728 $wLength, $self->_get_timeout_arg($timeout)
729 );
730 }
731  
732 sub check_abort_bulk_in_status {
733 my $self = shift;
734 my ($timeout) = validated_list( \@_, _timeout_arg() );
735  
736 $self->_debug("check abort bulk in status");
737 my $bmRequestType = 0xa2;
738 my $bRequest = CHECK_ABORT_BULK_IN_STATUS;
739 my $wValue = 0;
740 my $wIndex = $self->bulk_in_endpoint();
741 my $wLength = 8;
742 return $self->handle()->control_transfer_read(
743 $bmRequestType, $bRequest, $wValue, $wIndex,
744 $wLength, $self->_get_timeout_arg($timeout)
745 );
746 }
747  
748 =head2 clear
749  
750 $usbtmc->clear(timeout => $timeout);
751  
752 Do INITIATE_CLEAR / CHECK_CLEAR_STATUS split transaction. On success, send
753 CLEAR_FEATURE request to clear the Bulk-OUT Halt.
754  
755 =cut
756  
757 sub clear {
758 my $self = shift;
759 $self->clear_without_output_clear(@_);
760 my ($timeout) = validated_list( \@_, _timeout_arg() );
761  
762 # Required by USB-TMC standard?
763 $self->clear_feature_endpoint_out( timeout => $timeout );
764 }
765  
766 sub clear_without_output_clear {
767 my $self = shift;
768 my ($timeout) = validated_list( \@_, _timeout_arg() );
769 my $initiate_status = $self->initiate_clear( timeout => $timeout );
770 $initiate_status = unpack( 'C', $initiate_status );
771 if ( $initiate_status != STATUS_SUCCESS ) {
772 carp "INITIATE_CLEAR failed with status $initiate_status";
773 return;
774 }
775  
776 # Check clear status
777 while (1) {
778 my $clear_status = $self->check_clear_status( timeout => $timeout );
779 my $status = unpack( 'C', substr( $clear_status, 0, 1 ) );
780 my $bmClear = unpack( 'C', substr( $clear_status, 1, 1 ) );
781 if ( $status == STATUS_SUCCESS ) {
782 last;
783 }
784 elsif ( $status == STATUS_PENDING ) {
785 $self->_debug(
786 "CHECK_CLEAR_STATUS: status pending, bmClear = $bmClear");
787  
788 # If bmClear.D0 = 1, the Host should read from the
789 # Bulk-IN endpoint until a short packet is received.
790 if ( $bmClear & 1 ) {
791 my $endpoint = $self->bulk_in_endpoint();
792 my $data = $self->handle()->bulk_transfer_read(
793 $endpoint, 1000,
794 $self->_get_timeout_arg($timeout)
795 );
796 $self->_debug( " read bytes: ", length($data) );
797 }
798 next;
799 }
800 else {
801 croak "CHECK_CLEAR_STATUS failed with status $status";
802 }
803 }
804 }
805  
806  
807 sub initiate_clear {
808 my $self = shift;
809 my ($timeout) = validated_list( \@_, _timeout_arg() );
810  
811 $self->_debug("initiate clear");
812 my $bmRequestType = 0xa1;
813 my $bRequest = INITIATE_CLEAR;
814 my $wValue = 0;
815 my $wIndex = $self->interface_number();
816 my $wLength = 1;
817 return $self->handle()->control_transfer_read(
818 $bmRequestType, $bRequest, $wValue, $wIndex,
819 $wLength, $self->_get_timeout_arg($timeout)
820 );
821 }
822  
823 sub check_clear_status {
824 my $self = shift;
825 my ($timeout) = validated_list( \@_, _timeout_arg() );
826  
827 $self->_debug("check clear status");
828 my $bmRequestType = 0xa1;
829 my $bRequest = CHECK_CLEAR_STATUS;
830 my $wValue = 0;
831 my $wIndex = $self->interface_number();
832 my $wLength = 2;
833 return $self->handle()->control_transfer_read(
834 $bmRequestType, $bRequest, $wValue, $wIndex,
835 $wLength, $self->_get_timeout_arg($timeout)
836 );
837 }
838  
839 sub clear_feature_endpoint_out {
840 my $self = shift;
841 my ($timeout) = validated_list( \@_, _timeout_arg() );
842  
843 $self->_debug("clear feature endpoint out");
844 my $endpoint = $self->bulk_out_endpoint();
845 my $bmRequestType = LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_STANDARD
846 | LIBUSB_RECIPIENT_ENDPOINT;
847 my $bRequest = LIBUSB_REQUEST_CLEAR_FEATURE;
848 my $wValue = FEATURE_SELECTOR_ENDPOINT_HALT;
849 my $wIndex = $endpoint;
850 $self->handle()->control_transfer_write(
851 $bmRequestType, $bRequest, $wValue,
852 $wIndex, "", $self->_get_timeout_arg($timeout)
853 );
854 }
855  
856 sub clear_feature_endpoint_in {
857 my $self = shift;
858 my ($timeout) = validated_list( \@_, _timeout_arg() );
859  
860 $self->_debug("clear feature endpoint in");
861 my $endpoint = $self->bulk_in_endpoint();
862 my $bmRequestType = LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_STANDARD
863 | LIBUSB_RECIPIENT_ENDPOINT;
864 my $bRequest = LIBUSB_REQUEST_CLEAR_FEATURE;
865 my $wValue = FEATURE_SELECTOR_ENDPOINT_HALT;
866 my $wIndex = $endpoint;
867 $self->handle()->control_transfer_write(
868 $bmRequestType, $bRequest, $wValue,
869 $wIndex, "", $self->_get_timeout_arg($timeout)
870 );
871 }
872  
873 sub clear_halt_out {
874 my $self = shift;
875 my $endpoint = $self->bulk_out_endpoint();
876 $self->handle()->clear_halt($endpoint);
877 }
878  
879 sub clear_halt_in {
880 my $self = shift;
881 my $endpoint = $self->bulk_in_endpoint();
882 $self->handle()->clear_halt($endpoint);
883 }
884  
885 =head2 get_capabilities
886  
887 my $capabilites = $usbtmc->get_capabilities(timeout => $timeout);
888  
889 Do GET_CAPABILITIES request.
890  
891 The C<$capabilities> hash contains the following keys:
892  
893 =over
894  
895 =item bcdUSBTMC
896  
897 =item listen_only
898  
899 =item talk_only
900  
901 =item accept_indicator_pulse
902  
903 =item support_term_char
904  
905 =back
906  
907 =cut
908  
909 sub get_capabilities {
910 my $self = shift;
911 my ($timeout) = validated_list( \@_, _timeout_arg() );
912  
913 my $bmRequestType = 0xa1;
914 my $bRequest = 7;
915 my $wValue = 0;
916 my $wIndex = $self->interface_number();
917 my $wLength = 0x18;
918  
919 my $handle = $self->handle();
920 my $caps = $handle->control_transfer_read(
921 $bmRequestType, $bRequest, $wValue,
922 $wIndex, $wLength, $self->_get_timeout_arg($timeout)
923 );
924 if ( length $caps != $wLength ) {
925 croak "Incomplete response in get_capabilities.";
926 }
927  
928 my $status = unpack( 'C', substr( $caps, 0, 1 ) );
929  
930 if ( $status != 1 ) {
931 croak "GET_CAPABILITIES not successfull. status = $status";
932 }
933  
934 my $bcdUSBTMC = unpack( 'v', substr( $caps, 2, 2 ) );
935 my $interface_capabilities = unpack( 'C', substr( $caps, 4, 1 ) );
936 my $device_capabilites = unpack( 'C', substr( $caps, 5, 1 ) );
937  
938 return {
939 bcdUSBTMC => $bcdUSBTMC,
940 listen_only => $interface_capabilities & 1,
941 talk_only => ( $interface_capabilities >> 1 ) & 1,
942 accept_indicator_pulse => ( $interface_capabilities >> 2 ) & 1,
943 support_term_char => $device_capabilites & 1,
944 };
945 }
946  
947 __PACKAGE__->meta->make_immutable();
948  
949 1;
950  
951 =head1 REPORTING BUGS
952  
953 Please report bugs at L<https://github.com/lab-measurement/USB-TMC/issues>.
954  
955 =head1 CONTACT
956  
957 Feel free to contact us at the #labmeasurement channel on Freenode IRC.
958  
959 =head1 SEE ALSO
960  
961 =over
962  
963 =item * L<Blog post on Lab::VXI11 and USB::TMC|http://blogs.perl.org/users/simon_reinhardt/2017/10/labmeasurement-new-lightweight-backends-for-vxi-11-and-usb-tmc.html>
964  
965 =back
966  
967 =head1 AUTHOR
968  
969 Simon Reinhardt, E<lt>simon.reinhardt@physik.uni-r.deE<gt>
970  
971 =head1 COPYRIGHT AND LICENSE
972  
973 Copyright (C) 2017 by Simon Reinhardt
974  
975 This library is free software; you can redistribute it and/or modify
976 it under the same terms as Perl itself, either Perl version 5.24.0 or,
977 at your option, any later version of Perl 5 you may have available.
978  
979  
980 =cut
981  
↑ Summary