/
usb1.py
2160 lines (1931 loc) · 76.9 KB
/
usb1.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Copyright (C) 2010-2015 Vincent Pelletier <plr.vincent@gmail.com>
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
"""
Pythonic wrapper for libusb-1.0.
The first thing you must do is to get an "USB context". To do so, create an
USBContext instance.
Then, you can use it to browse available USB devices and open the one you want
to talk to.
At this point, you should have a USBDeviceHandle instance (as returned by
USBContext or USBDevice instances), and you can start exchanging with the
device.
Features:
- Basic device settings (configuration & interface selection, ...)
- String descriptor lookups (ASCII & unicode), and list supported language
codes
- Synchronous I/O (control, bulk, interrupt)
- Asynchronous I/O (control, bulk, interrupt, isochronous)
Note: Isochronous support is not well tested.
See USBPoller, USBTransfer and USBTransferHelper.
"""
import libusb1
from ctypes import byref, create_string_buffer, c_int, sizeof, POINTER, \
cast, c_uint8, c_uint16, c_ubyte, string_at, c_void_p, cdll, addressof
import sys
import threading
from ctypes.util import find_library
import warnings
import weakref
import collections
try:
namedtuple = collections.namedtuple
except AttributeError:
Version = lambda *x: x
else:
Version = namedtuple('Version', ['major', 'minor', 'micro', 'nano', 'rc',
'describe'])
if sys.version_info[0] == 3:
BYTE = bytes([0])
xrange = range
long = int
else:
BYTE = '\x00'
CONTROL_SETUP = BYTE * libusb1.LIBUSB_CONTROL_SETUP_SIZE
__all__ = ['USBContext', 'USBDeviceHandle', 'USBDevice',
'USBPoller', 'USBTransfer', 'USBTransferHelper', 'EVENT_CALLBACK_SET',
'USBPollerThread', 'USBEndpoint', 'USBInterfaceSetting', 'USBInterface',
'USBConfiguration', 'DoomedTransferError', 'getVersion',
]
if sys.version_info[:2] >= (2, 6):
if sys.platform == 'win32':
from ctypes import get_last_error as get_errno
else:
from ctypes import get_errno
else:
def get_errno():
raise NotImplementedError("Your python version doesn't support "
"errno/last_error")
__libc_name = find_library('c')
if __libc_name is None:
# Of course, will leak memory.
# Should we warn user ? How ?
_free = lambda x: None
else:
_free = getattr(cdll, __libc_name).free
del __libc_name
try:
WeakSet = weakref.WeakSet
except AttributeError:
# Python < 2.7: tiny wrapper around WeakKeyDictionary
class WeakSet(object):
def __init__(self):
self.__dict = weakref.WeakKeyDictionary()
def add(self, item):
self.__dict[item] = None
def pop(self):
return self.__dict.popitem()[0]
# Default string length
# From a comment in libusb-1.0: "Some devices choke on size > 255"
STRING_LENGTH = 255
# As of v3 of USB specs, there cannot be more than 7 hubs from controler to
# device.
PATH_MAX_DEPTH = 7
EVENT_CALLBACK_SET = frozenset((
libusb1.LIBUSB_TRANSFER_COMPLETED,
libusb1.LIBUSB_TRANSFER_ERROR,
libusb1.LIBUSB_TRANSFER_TIMED_OUT,
libusb1.LIBUSB_TRANSFER_CANCELLED,
libusb1.LIBUSB_TRANSFER_STALL,
libusb1.LIBUSB_TRANSFER_NO_DEVICE,
libusb1.LIBUSB_TRANSFER_OVERFLOW,
))
DEFAULT_ASYNC_TRANSFER_ERROR_CALLBACK = lambda x: False
def create_binary_buffer(string_or_len):
# Prevent ctypes from adding a trailing null char.
if isinstance(string_or_len, (int, long)):
result = create_string_buffer(string_or_len)
else:
result = create_string_buffer(string_or_len, len(string_or_len))
return result
class DoomedTransferError(Exception):
"""Exception raised when altering/submitting a doomed transfer."""
pass
class USBTransfer(object):
"""
USB asynchronous transfer control & data.
All modification methods will raise if called on a submitted transfer.
Methods noted as "should not be called on a submitted transfer" will not
prevent you from reading, but returned value is unspecified.
Note on user_data: because of pypy's current ctype restrictions, user_data
is not provided to C level, but is managed purely in python. It should
change nothing for you, unless you are looking at underlying C transfer
structure - which you should never have to.
"""
# Prevent garbage collector from freeing the free function before our
# instances, as we need it to property destruct them.
__libusb_free_transfer = libusb1.libusb_free_transfer
__libusb_cancel_transfer = libusb1.libusb_cancel_transfer
__USBError = libusb1.USBError
__LIBUSB_ERROR_NOT_FOUND = libusb1.LIBUSB_ERROR_NOT_FOUND
__transfer = None
__initialized = False
__submitted = False
__callback = None
__ctypesCallbackWrapper = None
__doomed = False
__user_data = None
__transfer_buffer = None
def __init__(self, handle, iso_packets, before_submit, after_completion):
"""
You should not instanciate this class directly.
Call "getTransfer" method on an USBDeviceHandle instance to get
instances of this class.
"""
if iso_packets < 0:
raise ValueError('Cannot request a negative number of iso '
'packets.')
self.__handle = handle
self.__before_submit = before_submit
self.__after_completion = after_completion
self.__num_iso_packets = iso_packets
result = libusb1.libusb_alloc_transfer(iso_packets)
if not result:
raise libusb1.USBError('Unable to get a transfer object')
self.__transfer = result
self.__ctypesCallbackWrapper = libusb1.libusb_transfer_cb_fn_p(
self.__callbackWrapper)
def close(self):
"""
Break reference cycles to allow instance to be garbage-collected.
Raises if called on a submitted transfer.
"""
if self.__submitted:
raise ValueError('Cannot close a submitted transfer')
self.doom()
self.__initialized = False
# Break possible external reference cycles
self.__callback = None
self.__user_data = None
# Break libusb_transfer reference cycles
self.__ctypesCallbackWrapper = None
# For some reason, overwriting callback is not enough to remove this
# reference cycle - though sometimes it works:
# self -> self.__dict__ -> libusb_transfer -> dict[x] -> dict[x] ->
# CThunkObject -> __callbackWrapper -> self
# So free transfer altogether.
if self.__transfer is not None:
self.__libusb_free_transfer(self.__transfer)
self.__transfer = None
self.__transfer_buffer = None
# Break USBDeviceHandle reference cycle
self.__before_submit = None
self.__after_completion = None
def doom(self):
"""
Prevent transfer from being submitted again.
"""
self.__doomed = True
def __del__(self):
if self.__transfer is not None:
try:
# If this doesn't raise, we're doomed; transfer was submitted,
# still python decided to garbage-collect this instance.
# Stick to libusb's documentation, and don't free the
# transfer. If interpreter is shutting down, kernel will
# reclaim memory anyway.
# Note: we can't prevent transfer's buffer from being
# garbage-collected as soon as there will be no remaining
# reference to transfer, so a segfault might happen anyway.
# Should we warn user ? How ?
self.cancel()
except self.__USBError:
if sys.exc_info()[1].value == self.__LIBUSB_ERROR_NOT_FOUND:
# Transfer was not submitted, we can free it.
self.__libusb_free_transfer(self.__transfer)
else:
raise
def __callbackWrapper(self, transfer_p):
"""
Makes it possible for user-provided callback to alter transfer when
fired (ie, mark transfer as not submitted upon call).
"""
self.__submitted = False
self.__after_completion(self)
callback = self.__callback
if callback is not None:
callback(self)
if self.__doomed:
self.close()
def setCallback(self, callback):
"""
Change transfer's callback.
"""
self.__callback = callback
def getCallback(self):
"""
Get currently set callback.
"""
return self.__callback
def setControl(self, request_type, request, value, index, buffer_or_len,
callback=None, user_data=None, timeout=0):
"""
Setup transfer for control use.
request_type, request, value, index
See USBDeviceHandle.controlWrite.
request_type defines transfer direction (see
libusb1.LIBUSB_ENDPOINT_OUT and libusb1.LIBUSB_ENDPOINT_IN)).
buffer_or_len
Either a string (when sending data), or expected data length (when
receiving data).
callback
Callback function to be invoked on transfer completion.
Called with transfer as parameter, return value ignored.
user_data
User data to pass to callback function.
timeout
Transfer timeout in milliseconds. 0 to disable.
"""
if self.__submitted:
raise ValueError('Cannot alter a submitted transfer')
if self.__doomed:
raise DoomedTransferError('Cannot reuse a doomed transfer')
if isinstance(buffer_or_len, (int, long)):
length = buffer_or_len
string_buffer = create_binary_buffer(length +
libusb1.LIBUSB_CONTROL_SETUP_SIZE)
else:
length = len(buffer_or_len)
string_buffer = create_binary_buffer(CONTROL_SETUP + buffer_or_len)
self.__initialized = False
self.__transfer_buffer = string_buffer
self.__user_data = user_data
libusb1.libusb_fill_control_setup(string_buffer, request_type,
request, value, index, length)
libusb1.libusb_fill_control_transfer(self.__transfer, self.__handle,
string_buffer, self.__ctypesCallbackWrapper, None, timeout)
self.__callback = callback
self.__initialized = True
def setBulk(self, endpoint, buffer_or_len, callback=None, user_data=None,
timeout=0):
"""
Setup transfer for bulk use.
endpoint
Endpoint to submit transfer to. Defines transfer direction (see
libusb1.LIBUSB_ENDPOINT_OUT and libusb1.LIBUSB_ENDPOINT_IN)).
buffer_or_len
Either a string (when sending data), or expected data length (when
receiving data)
callback
Callback function to be invoked on transfer completion.
Called with transfer as parameter, return value ignored.
user_data
User data to pass to callback function.
timeout
Transfer timeout in milliseconds. 0 to disable.
"""
if self.__submitted:
raise ValueError('Cannot alter a submitted transfer')
if self.__doomed:
raise DoomedTransferError('Cannot reuse a doomed transfer')
string_buffer = create_binary_buffer(buffer_or_len)
self.__initialized = False
self.__transfer_buffer = string_buffer
self.__user_data = user_data
libusb1.libusb_fill_bulk_transfer(self.__transfer, self.__handle,
endpoint, string_buffer, sizeof(string_buffer),
self.__ctypesCallbackWrapper, None, timeout)
self.__callback = callback
self.__initialized = True
def setInterrupt(self, endpoint, buffer_or_len, callback=None,
user_data=None, timeout=0):
"""
Setup transfer for interrupt use.
endpoint
Endpoint to submit transfer to. Defines transfer direction (see
libusb1.LIBUSB_ENDPOINT_OUT and libusb1.LIBUSB_ENDPOINT_IN)).
buffer_or_len
Either a string (when sending data), or expected data length (when
receiving data)
callback
Callback function to be invoked on transfer completion.
Called with transfer as parameter, return value ignored.
user_data
User data to pass to callback function.
timeout
Transfer timeout in milliseconds. 0 to disable.
"""
if self.__submitted:
raise ValueError('Cannot alter a submitted transfer')
if self.__doomed:
raise DoomedTransferError('Cannot reuse a doomed transfer')
string_buffer = create_binary_buffer(buffer_or_len)
self.__initialized = False
self.__transfer_buffer = string_buffer
self.__user_data = user_data
libusb1.libusb_fill_interrupt_transfer(self.__transfer, self.__handle,
endpoint, string_buffer, sizeof(string_buffer),
self.__ctypesCallbackWrapper, None, timeout)
self.__callback = callback
self.__initialized = True
def setIsochronous(self, endpoint, buffer_or_len, callback=None,
user_data=None, timeout=0, iso_transfer_length_list=None):
"""
Setup transfer for isochronous use.
endpoint
Endpoint to submit transfer to. Defines transfer direction (see
libusb1.LIBUSB_ENDPOINT_OUT and libusb1.LIBUSB_ENDPOINT_IN)).
buffer_or_len
Either a string (when sending data), or expected data length (when
receiving data)
callback
Callback function to be invoked on transfer completion.
Called with transfer as parameter, return value ignored.
user_data
User data to pass to callback function.
timeout
Transfer timeout in milliseconds. 0 to disable.
iso_transfer_length_list
List of individual transfer sizes. If not provided, buffer_or_len
will be divided evenly among available transfers if possible, and
raise ValueError otherwise.
"""
if self.__submitted:
raise ValueError('Cannot alter a submitted transfer')
num_iso_packets = self.__num_iso_packets
if num_iso_packets == 0:
raise TypeError('This transfer canot be used for isochronous I/O. '
'You must get another one with a non-zero iso_packets '
'parameter.')
if self.__doomed:
raise DoomedTransferError('Cannot reuse a doomed transfer')
string_buffer = create_binary_buffer(buffer_or_len)
buffer_length = sizeof(string_buffer)
if iso_transfer_length_list is None:
iso_length, remainder = divmod(buffer_length, num_iso_packets)
if remainder:
raise ValueError('Buffer size %i cannot be evenly '
'distributed among %i transfers' % (buffer_length,
num_iso_packets))
iso_transfer_length_list = [iso_length] * num_iso_packets
configured_iso_packets = len(iso_transfer_length_list)
if configured_iso_packets > num_iso_packets:
raise ValueError('Too many ISO transfer lengths (%i), there are '
'only %i ISO transfers available' % (configured_iso_packets,
num_iso_packets))
if sum(iso_transfer_length_list) > buffer_length:
raise ValueError('ISO transfers too long (%i), there are only '
'%i bytes available' % (sum(iso_transfer_length_list),
buffer_length))
transfer_p = self.__transfer
self.__initialized = False
self.__transfer_buffer = string_buffer
self.__user_data = user_data
libusb1.libusb_fill_iso_transfer(transfer_p, self.__handle,
endpoint, string_buffer, buffer_length, configured_iso_packets,
self.__ctypesCallbackWrapper, None, timeout)
for length, iso_packet_desc in zip(iso_transfer_length_list,
libusb1.get_iso_packet_list(transfer_p)):
if length <= 0:
raise ValueError('Negative/null length transfers are not '
'possible.')
iso_packet_desc.length = length
self.__callback = callback
self.__initialized = True
def getType(self):
"""
Get transfer type.
See libusb1.libusb_transfer_type.
"""
return self.__transfer.contents.type
def getEndpoint(self):
"""
Get endpoint.
"""
return self.__transfer.contents.endpoint
def getStatus(self):
"""
Get transfer status.
Should not be called on a submitted transfer.
"""
return self.__transfer.contents.status
def getActualLength(self):
"""
Get actually transfered data length.
Should not be called on a submitted transfer.
"""
return self.__transfer.contents.actual_length
def getBuffer(self):
"""
Get data buffer content.
Should not be called on a submitted transfer.
"""
transfer_p = self.__transfer
transfer = transfer_p.contents
if transfer.type == libusb1.LIBUSB_TRANSFER_TYPE_CONTROL:
result = libusb1.libusb_control_transfer_get_data(transfer_p)
else:
result = string_at(transfer.buffer, transfer.length)
return result
def getUserData(self):
"""
Retrieve user data provided on setup.
"""
return self.__user_data
def setUserData(self, user_data):
"""
Change user data.
"""
self.__user_data = user_data
def getISOBufferList(self):
"""
Get individual ISO transfer's buffer.
Returns a list with one item per ISO transfer, with their
individually-configured sizes.
Returned list is consistent with getISOSetupList return value.
Should not be called on a submitted transfer.
See also iterISO.
"""
transfer_p = self.__transfer
transfer = transfer_p.contents
if transfer.type != libusb1.LIBUSB_TRANSFER_TYPE_ISOCHRONOUS:
raise TypeError('This method cannot be called on non-iso '
'transfers.')
return libusb1.get_iso_packet_buffer_list(transfer_p)
def getISOSetupList(self):
"""
Get individual ISO transfer's setup.
Returns a list of dicts, each containing an individual ISO transfer
parameters:
- length
- actual_length
- status
(see libusb1's API documentation for their signification)
Returned list is consistent with getISOBufferList return value.
Should not be called on a submitted transfer (except for 'length'
values).
"""
transfer_p = self.__transfer
transfer = transfer_p.contents
if transfer.type != libusb1.LIBUSB_TRANSFER_TYPE_ISOCHRONOUS:
raise TypeError('This method cannot be called on non-iso '
'transfers.')
return [{
'length': x.length,
'actual_length': x.actual_length,
'status': x.status,
} for x in libusb1.get_iso_packet_list(transfer_p)]
def iterISO(self):
"""
Generator yielding (status, buffer) for each isochornous transfer.
buffer is truncated to actual_length.
This is more efficient than calling both getISOBufferList and
getISOSetupList when receiving data.
Should not be called on a submitted transfer.
"""
transfer_p = self.__transfer
transfer = transfer_p.contents
if transfer.type != libusb1.LIBUSB_TRANSFER_TYPE_ISOCHRONOUS:
raise TypeError('This method cannot be called on non-iso '
'transfers.')
buffer_position = transfer.buffer
for iso_transfer in libusb1.get_iso_packet_list(transfer_p):
yield (
iso_transfer.status,
string_at(buffer_position, iso_transfer.actual_length),
)
buffer_position += iso_transfer.length
def setBuffer(self, buffer_or_len):
"""
Replace buffer with a new one.
Allows resizing read buffer and replacing data sent.
Note: resizing is not allowed for isochronous buffer (use
setIsochronous).
Note: disallowed on control transfers (use setControl).
"""
if self.__submitted:
raise ValueError('Cannot alter a submitted transfer')
transfer = self.__transfer.contents
if transfer.type == libusb1.LIBUSB_TRANSFER_TYPE_CONTROL:
raise ValueError('To alter control transfer buffer, use '
'setControl')
buff = create_binary_buffer(buffer_or_len)
if transfer.type == libusb1.LIBUSB_TRANSFER_TYPE_ISOCHRONOUS and \
sizeof(buff) != transfer.length:
raise ValueError('To alter isochronous transfer buffer length, '
'use setIsochronous')
self.__transfer_buffer = buff
transfer.buffer = cast(buff, c_void_p)
transfer.length = sizeof(buff)
def isSubmitted(self):
"""
Tells if this transfer is submitted and still pending.
"""
return self.__submitted
def submit(self):
"""
Submit transfer for asynchronous handling.
"""
if self.__submitted:
raise ValueError('Cannot submit a submitted transfer')
if not self.__initialized:
raise ValueError('Cannot submit a transfer until it has been '
'initialized')
if self.__doomed:
raise DoomedTransferError('Cannot submit doomed transfer')
self.__before_submit(self)
self.__submitted = True
result = libusb1.libusb_submit_transfer(self.__transfer)
if result:
self.__after_completion(self)
self.__submitted = False
raise libusb1.USBError(result)
def cancel(self):
"""
Cancel transfer.
Note: cancellation happens asynchronously, so you must wait for
LIBUSB_TRANSFER_CANCELLED.
"""
if not self.__submitted:
# XXX: Workaround for a bug reported on libusb 1.0.8: calling
# libusb_cancel_transfer on a non-submitted transfer might
# trigger a segfault.
raise self.__USBError(self.__LIBUSB_ERROR_NOT_FOUND)
result = self.__libusb_cancel_transfer(self.__transfer)
if result:
raise self.__USBError(result)
class USBTransferHelper(object):
"""
Simplifies subscribing to the same transfer over and over, and callback
handling:
- no need to read event status to execute apropriate code, just setup
different functions for each status code
- just return True instead of calling submit
- no need to check if transfer is doomed before submitting it again,
DoomedTransferError is caught.
Callbacks used in this class must follow the callback API described in
USBTransfer, and are expected to return a boolean:
- True if transfer is to be submitted again (to receive/send more data)
- False otherwise
Note: as per libusb1 specifications, isochronous transfer global state
might be LIBUSB_TRANSFER_COMPLETED although some individual packets might
have an error status. You can check individual packet status by calling
getISOSetupList on transfer object in your callback.
"""
def __init__(self, transfer=None):
"""
Create a transfer callback dispatcher.
transfer parameter is deprecated. If provided, it will be equivalent
to:
helper = USBTransferHelper()
transfer.setCallback(helper)
and also allows using deprecated methods on this class (otherwise,
they raise AttributeError).
"""
if transfer is not None:
# Deprecated: to drop
self.__transfer = transfer
transfer.setCallback(self)
self.__event_callback_dict = {}
self.__errorCallback = DEFAULT_ASYNC_TRANSFER_ERROR_CALLBACK
def submit(self):
"""
Submit the asynchronous read request.
Deprecated. Use submit on transfer.
"""
# Deprecated: to drop
self.__transfer.submit()
def cancel(self):
"""
Cancel a pending read request.
Deprecated. Use cancel on transfer.
"""
# Deprecated: to drop
self.__transfer.cancel()
def setEventCallback(self, event, callback):
"""
Set a function to call for a given event.
Possible event identifiers are listed in EVENT_CALLBACK_SET.
"""
if event not in EVENT_CALLBACK_SET:
raise ValueError('Unknown event %r.' % (event, ))
self.__event_callback_dict[event] = callback
def setDefaultCallback(self, callback):
"""
Set the function to call for event which don't have a specific callback
registered.
The initial default callback does nothing and returns False.
"""
self.__errorCallback = callback
def getEventCallback(self, event, default=None):
"""
Return the function registered to be called for given event identifier.
"""
return self.__event_callback_dict.get(event, default)
def __call__(self, transfer):
"""
Callback to set on transfers.
"""
if self.getEventCallback(transfer.getStatus(), self.__errorCallback)(
transfer):
try:
transfer.submit()
except DoomedTransferError:
pass
def isSubmited(self):
"""
Returns whether this reader is currently waiting for an event.
Deprecatd. Use isSubmitted on transfer.
"""
# Deprecated: to drop
return self.__transfer.isSubmitted()
class USBPollerThread(threading.Thread):
"""
Implements libusb1 documentation about threaded, asynchronous
applications.
In short, instanciate this class once (...per USBContext instance), call
start() on the instance, and do whatever you need.
This thread will be used to execute transfer completion callbacks, and you
are free to use libusb1's synchronous API in another thread, and can forget
about libusb1 file descriptors.
See http://libusb.sourceforge.net/api-1.0/mtasync.html .
"""
def __init__(self, context, poller, exc_callback=None):
"""
Create a poller thread for given context.
Warning: it will not check if another poller instance was already
present for that context, and will replace it.
poller
(same as USBPoller.__init__ "poller" parameter)
exc_callback (callable)
Called with a libusb_error value as single parameter when event
handling fails.
If not given, an USBError will be raised, interrupting the thread.
"""
super(USBPollerThread, self).__init__()
self.daemon = True
self.__context = context
self.__poller = poller
self.__fd_set = set()
context.setPollFDNotifiers(self._registerFD, self._unregisterFD)
for fd, events in context.getPollFDList():
self._registerFD(fd, events, None)
if exc_callback is not None:
self.exceptionHandler = exc_callback
def __del__(self):
self.__context.setPollFDNotifiers(None, None)
@staticmethod
def exceptionHandler(exc):
raise exc
def run(self):
# We expect quite some spinning in below loop, so move any unneeded
# operation out of it.
context = self.__context
poll = self.__poller.poll
try_lock_events = context.tryLockEvents
lock_event_waiters = context.lockEventWaiters
wait_for_event = context.waitForEvent
unlock_event_waiters = context.unlockEventWaiters
event_handling_ok = context.eventHandlingOK
unlock_events = context.unlockEvents
handle_events_locked = context.handleEventsLocked
event_handler_active = context.eventHandlerActive
getNextTimeout = context.getNextTimeout
exceptionHandler = self.exceptionHandler
fd_set = self.__fd_set
while fd_set:
if try_lock_events():
lock_event_waiters()
while event_handler_active():
wait_for_event()
unlock_event_waiters()
else:
try:
while event_handling_ok():
if poll(getNextTimeout()):
try:
handle_events_locked()
except libusb1.USBError:
exceptionHandler(sys.exc_info()[1])
finally:
unlock_events()
def _registerFD(self, fd, events, _):
self.__poller.register(fd, events)
self.__fd_set.add(fd)
def _unregisterFD(self, fd, _):
self.__fd_set.discard(fd)
self.__poller.unregister(fd)
class USBPoller(object):
"""
Class allowing integration of USB event polling in a file-descriptor
monitoring event loop.
WARNING: Do not call "poll" from several threads concurently. Do not use
synchronous USB transfers in a thread while "poll" is running. Doing so
will result in unnecessarily long pauses in some threads. Opening and/or
closing devices while polling can cause race conditions to occur.
"""
def __init__(self, context, poller):
"""
Create a poller for given context.
Warning: it will not check if another poller instance was already
present for that context, and will replace it.
poller is a polling instance implementing the following methods:
- register(fd, event_flags)
event_flags have the same meaning as in poll API (POLLIN & POLLOUT)
- unregister(fd)
- poll(timeout)
timeout being a float in seconds, or negative/None if there is no
timeout.
It must return a list of (descriptor, event) pairs.
Note: USBPoller is itself a valid poller.
Note2: select.poll uses a timeout in milliseconds, for some reason
(all other select.* classes use seconds for timeout), so you should
wrap it to convert & round/truncate timeout.
"""
self.__context = context
self.__poller = poller
self.__fd_set = set()
context.setPollFDNotifiers(self._registerFD, self._unregisterFD)
for fd, events in context.getPollFDList():
self._registerFD(fd, events)
def __del__(self):
self.__context.setPollFDNotifiers(None, None)
def poll(self, timeout=None):
"""
Poll for events.
timeout can be a float in seconds, or None for no timeout.
Returns a list of (descriptor, event) pairs.
"""
next_usb_timeout = self.__context.getNextTimeout()
if timeout is None or timeout < 0:
usb_timeout = next_usb_timeout
elif next_usb_timeout:
usb_timeout = min(next_usb_timeout, timeout)
else:
usb_timeout = timeout
event_list = self.__poller.poll(usb_timeout)
if event_list:
fd_set = self.__fd_set
result = [(x, y) for x, y in event_list if x not in fd_set]
if len(result) != len(event_list):
self.__context.handleEventsTimeout()
else:
result = event_list
self.__context.handleEventsTimeout()
return result
def register(self, fd, events):
"""
Register an USB-unrelated fd to poller.
Convenience method.
"""
if fd in self.__fd_set:
raise ValueError('This fd is a special USB event fd, it cannot '
'be polled.')
self.__poller.register(fd, events)
def unregister(self, fd):
"""
Unregister an USB-unrelated fd from poller.
Convenience method.
"""
if fd in self.__fd_set:
raise ValueError('This fd is a special USB event fd, it must '
'stay registered.')
self.__poller.unregister(fd)
def _registerFD(self, fd, events, user_data=None):
self.register(fd, events)
self.__fd_set.add(fd)
def _unregisterFD(self, fd, user_data=None):
self.__fd_set.discard(fd)
self.unregister(fd)
class USBDeviceHandle(object):
"""
Represents an opened USB device.
"""
__handle = None
__libusb_close = libusb1.libusb_close
__USBError = libusb1.USBError
__LIBUSB_ERROR_NOT_FOUND = libusb1.LIBUSB_ERROR_NOT_FOUND
__LIBUSB_ERROR_NO_DEVICE = libusb1.LIBUSB_ERROR_NO_DEVICE
__LIBUSB_ERROR_INTERRUPTED = libusb1.LIBUSB_ERROR_INTERRUPTED
__set = set
__KeyError = KeyError
__sys = sys
def __init__(self, context, handle, device):
"""
You should not instanciate this class directly.
Call "open" method on an USBDevice instance to get an USBDeviceHandle
instance.
"""
self.__context = context
# Weak reference to transfers about this device so we can clean up
# before closing device.
self.__transfer_set = WeakSet()
# Strong references to inflight transfers so they do not get freed
# even if user drops all strong references to them. If this instance
# is garbage-collected, we close all transfers, so it's fine.
self.__inflight = inflight = set()
# XXX: For some reason, doing self.__inflight.{add|remove} inside
# getTransfer causes extra intermediate python objects for each
# allocated transfer. Storing them as properties solves this. Found
# with objgraph.
self.__inflight_add = inflight.add
self.__inflight_remove = inflight.remove
self.__handle = handle
self.__device = device
def __del__(self):
self.close()
def close(self):
"""
Close this handle. If not called explicitely, will be called by
destructor.
This method cancels any in-flight transfer when it is called. As
cancellation is not immediate, this method needs to let libusb handle
events until transfers are actually cancelled.
In multi-threaded programs, this can lead to stalls. To avoid this,
do not close nor let GC collect a USBDeviceHandle which has in-flight
transfers.
"""
handle = self.__handle
if handle is not None:
# Build a strong set from weak self.__transfer_set so we can doom
# and close all contained transfers.
# Because of backward compatibility, self.__transfer_set might be a
# wrapper around WeakKeyDictionary. As it might be modified by gc,
# we must pop until there is not key left instead of iterating over
# it.
weak_transfer_set = self.__transfer_set
transfer_set = self.__set()
while True:
try:
transfer = weak_transfer_set.pop()
except self.__KeyError:
break
transfer_set.add(transfer)
transfer.doom()
inflight = self.__inflight
for transfer in inflight:
try:
transfer.cancel()
except self.__USBError:
if self.__sys.exc_info()[1].value not in (\
self.__LIBUSB_ERROR_NOT_FOUND,
self.__LIBUSB_ERROR_NO_DEVICE,
):
raise
while inflight:
try:
self.__context.handleEvents()
except self.__USBError:
if self.__sys.exc_info()[1].value != \
self.__LIBUSB_ERROR_INTERRUPTED:
raise
for transfer in transfer_set:
transfer.close()
self.__libusb_close(handle)
self.__handle = None
def getDevice(self):
"""
Get an USBDevice instance for the device accessed through this handle.
Useful for example to query its configurations.
"""
return self.__device
def getConfiguration(self):
"""
Get the current configuration number for this device.
"""
configuration = c_int()
result = libusb1.libusb_get_configuration(self.__handle,
byref(configuration))
if result:
raise libusb1.USBError(result)
return configuration.value
def setConfiguration(self, configuration):
"""
Set the configuration number for this device.
"""
result = libusb1.libusb_set_configuration(self.__handle, configuration)
if result:
raise libusb1.USBError(result)
def claimInterface(self, interface):
"""
Claim (= get exclusive access to) given interface number. Required to