| 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 | |||