libusb 0.6.0-x86-linux
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.gitignore +8 -0
- data/.travis.yml +17 -0
- data/.yardopts +6 -0
- data/COPYING +165 -0
- data/Gemfile +11 -0
- data/History.md +124 -0
- data/README.md +159 -0
- data/Rakefile +145 -0
- data/appveyor.yml +23 -0
- data/lib/libusb.rb +58 -0
- data/lib/libusb/bos.rb +306 -0
- data/lib/libusb/call.rb +446 -0
- data/lib/libusb/compat.rb +376 -0
- data/lib/libusb/configuration.rb +155 -0
- data/lib/libusb/constants.rb +160 -0
- data/lib/libusb/context.rb +426 -0
- data/lib/libusb/dependencies.rb +7 -0
- data/lib/libusb/dev_handle.rb +564 -0
- data/lib/libusb/device.rb +365 -0
- data/lib/libusb/endpoint.rb +194 -0
- data/lib/libusb/eventmachine.rb +183 -0
- data/lib/libusb/interface.rb +60 -0
- data/lib/libusb/setting.rb +132 -0
- data/lib/libusb/ss_companion.rb +69 -0
- data/lib/libusb/stdio.rb +25 -0
- data/lib/libusb/transfer.rb +377 -0
- data/lib/libusb/version_gem.rb +19 -0
- data/lib/libusb/version_struct.rb +63 -0
- data/libusb.gemspec +30 -0
- data/test/test_libusb_bos.rb +118 -0
- data/test/test_libusb_bulk_stream_transfer.rb +50 -0
- data/test/test_libusb_capability.rb +23 -0
- data/test/test_libusb_compat.rb +78 -0
- data/test/test_libusb_compat_mass_storage.rb +81 -0
- data/test/test_libusb_descriptors.rb +212 -0
- data/test/test_libusb_event_machine.rb +118 -0
- data/test/test_libusb_gc.rb +37 -0
- data/test/test_libusb_hotplug.rb +127 -0
- data/test/test_libusb_iso_transfer.rb +50 -0
- data/test/test_libusb_mass_storage.rb +268 -0
- data/test/test_libusb_mass_storage2.rb +96 -0
- data/test/test_libusb_structs.rb +58 -0
- data/test/test_libusb_threads.rb +89 -0
- data/test/test_libusb_version.rb +40 -0
- data/wireshark-usb-sniffer.png +0 -0
- metadata +150 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 8745d74ba38a4b244a0a767c9f8d8b11399cb788
|
4
|
+
data.tar.gz: dfbabc151f3b6098b888a3a4c616d14d4053f079
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: caa29ff2a44bd7d16ec6f8b66df34c3cf071b08783dc50f47476739eb18ca30cbd1c5c63c18c83f6914f5d9413c039125fcb4aed4f96420331c7ecd4c7af48f8
|
7
|
+
data.tar.gz: b62f5112cc342bc683e7b625e0db0bc5b50088217f504148b1ed2fffec20c2cf8d05bd6da42607df8cd8a2298441a9d1be781727c9b2aa95768c86da02ac75f9
|
data/.gitignore
ADDED
data/.travis.yml
ADDED
@@ -0,0 +1,17 @@
|
|
1
|
+
language: ruby
|
2
|
+
sudo: false
|
3
|
+
rvm:
|
4
|
+
- "1.9.3"
|
5
|
+
- "2.0.0"
|
6
|
+
- "2.1"
|
7
|
+
- "2.2"
|
8
|
+
- "2.3.1"
|
9
|
+
- "2.3.1-clang"
|
10
|
+
- jruby-1.7.26
|
11
|
+
- jruby-9.1.5.0
|
12
|
+
- rbx
|
13
|
+
matrix:
|
14
|
+
allow_failures:
|
15
|
+
- rvm: rbx
|
16
|
+
- rvm: "2.3.1-clang"
|
17
|
+
script: bundle exec rake travis
|
data/.yardopts
ADDED
data/COPYING
ADDED
@@ -0,0 +1,165 @@
|
|
1
|
+
GNU LESSER GENERAL PUBLIC LICENSE
|
2
|
+
Version 3, 29 June 2007
|
3
|
+
|
4
|
+
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
|
5
|
+
Everyone is permitted to copy and distribute verbatim copies
|
6
|
+
of this license document, but changing it is not allowed.
|
7
|
+
|
8
|
+
|
9
|
+
This version of the GNU Lesser General Public License incorporates
|
10
|
+
the terms and conditions of version 3 of the GNU General Public
|
11
|
+
License, supplemented by the additional permissions listed below.
|
12
|
+
|
13
|
+
0. Additional Definitions.
|
14
|
+
|
15
|
+
As used herein, "this License" refers to version 3 of the GNU Lesser
|
16
|
+
General Public License, and the "GNU GPL" refers to version 3 of the GNU
|
17
|
+
General Public License.
|
18
|
+
|
19
|
+
"The Library" refers to a covered work governed by this License,
|
20
|
+
other than an Application or a Combined Work as defined below.
|
21
|
+
|
22
|
+
An "Application" is any work that makes use of an interface provided
|
23
|
+
by the Library, but which is not otherwise based on the Library.
|
24
|
+
Defining a subclass of a class defined by the Library is deemed a mode
|
25
|
+
of using an interface provided by the Library.
|
26
|
+
|
27
|
+
A "Combined Work" is a work produced by combining or linking an
|
28
|
+
Application with the Library. The particular version of the Library
|
29
|
+
with which the Combined Work was made is also called the "Linked
|
30
|
+
Version".
|
31
|
+
|
32
|
+
The "Minimal Corresponding Source" for a Combined Work means the
|
33
|
+
Corresponding Source for the Combined Work, excluding any source code
|
34
|
+
for portions of the Combined Work that, considered in isolation, are
|
35
|
+
based on the Application, and not on the Linked Version.
|
36
|
+
|
37
|
+
The "Corresponding Application Code" for a Combined Work means the
|
38
|
+
object code and/or source code for the Application, including any data
|
39
|
+
and utility programs needed for reproducing the Combined Work from the
|
40
|
+
Application, but excluding the System Libraries of the Combined Work.
|
41
|
+
|
42
|
+
1. Exception to Section 3 of the GNU GPL.
|
43
|
+
|
44
|
+
You may convey a covered work under sections 3 and 4 of this License
|
45
|
+
without being bound by section 3 of the GNU GPL.
|
46
|
+
|
47
|
+
2. Conveying Modified Versions.
|
48
|
+
|
49
|
+
If you modify a copy of the Library, and, in your modifications, a
|
50
|
+
facility refers to a function or data to be supplied by an Application
|
51
|
+
that uses the facility (other than as an argument passed when the
|
52
|
+
facility is invoked), then you may convey a copy of the modified
|
53
|
+
version:
|
54
|
+
|
55
|
+
a) under this License, provided that you make a good faith effort to
|
56
|
+
ensure that, in the event an Application does not supply the
|
57
|
+
function or data, the facility still operates, and performs
|
58
|
+
whatever part of its purpose remains meaningful, or
|
59
|
+
|
60
|
+
b) under the GNU GPL, with none of the additional permissions of
|
61
|
+
this License applicable to that copy.
|
62
|
+
|
63
|
+
3. Object Code Incorporating Material from Library Header Files.
|
64
|
+
|
65
|
+
The object code form of an Application may incorporate material from
|
66
|
+
a header file that is part of the Library. You may convey such object
|
67
|
+
code under terms of your choice, provided that, if the incorporated
|
68
|
+
material is not limited to numerical parameters, data structure
|
69
|
+
layouts and accessors, or small macros, inline functions and templates
|
70
|
+
(ten or fewer lines in length), you do both of the following:
|
71
|
+
|
72
|
+
a) Give prominent notice with each copy of the object code that the
|
73
|
+
Library is used in it and that the Library and its use are
|
74
|
+
covered by this License.
|
75
|
+
|
76
|
+
b) Accompany the object code with a copy of the GNU GPL and this license
|
77
|
+
document.
|
78
|
+
|
79
|
+
4. Combined Works.
|
80
|
+
|
81
|
+
You may convey a Combined Work under terms of your choice that,
|
82
|
+
taken together, effectively do not restrict modification of the
|
83
|
+
portions of the Library contained in the Combined Work and reverse
|
84
|
+
engineering for debugging such modifications, if you also do each of
|
85
|
+
the following:
|
86
|
+
|
87
|
+
a) Give prominent notice with each copy of the Combined Work that
|
88
|
+
the Library is used in it and that the Library and its use are
|
89
|
+
covered by this License.
|
90
|
+
|
91
|
+
b) Accompany the Combined Work with a copy of the GNU GPL and this license
|
92
|
+
document.
|
93
|
+
|
94
|
+
c) For a Combined Work that displays copyright notices during
|
95
|
+
execution, include the copyright notice for the Library among
|
96
|
+
these notices, as well as a reference directing the user to the
|
97
|
+
copies of the GNU GPL and this license document.
|
98
|
+
|
99
|
+
d) Do one of the following:
|
100
|
+
|
101
|
+
0) Convey the Minimal Corresponding Source under the terms of this
|
102
|
+
License, and the Corresponding Application Code in a form
|
103
|
+
suitable for, and under terms that permit, the user to
|
104
|
+
recombine or relink the Application with a modified version of
|
105
|
+
the Linked Version to produce a modified Combined Work, in the
|
106
|
+
manner specified by section 6 of the GNU GPL for conveying
|
107
|
+
Corresponding Source.
|
108
|
+
|
109
|
+
1) Use a suitable shared library mechanism for linking with the
|
110
|
+
Library. A suitable mechanism is one that (a) uses at run time
|
111
|
+
a copy of the Library already present on the user's computer
|
112
|
+
system, and (b) will operate properly with a modified version
|
113
|
+
of the Library that is interface-compatible with the Linked
|
114
|
+
Version.
|
115
|
+
|
116
|
+
e) Provide Installation Information, but only if you would otherwise
|
117
|
+
be required to provide such information under section 6 of the
|
118
|
+
GNU GPL, and only to the extent that such information is
|
119
|
+
necessary to install and execute a modified version of the
|
120
|
+
Combined Work produced by recombining or relinking the
|
121
|
+
Application with a modified version of the Linked Version. (If
|
122
|
+
you use option 4d0, the Installation Information must accompany
|
123
|
+
the Minimal Corresponding Source and Corresponding Application
|
124
|
+
Code. If you use option 4d1, you must provide the Installation
|
125
|
+
Information in the manner specified by section 6 of the GNU GPL
|
126
|
+
for conveying Corresponding Source.)
|
127
|
+
|
128
|
+
5. Combined Libraries.
|
129
|
+
|
130
|
+
You may place library facilities that are a work based on the
|
131
|
+
Library side by side in a single library together with other library
|
132
|
+
facilities that are not Applications and are not covered by this
|
133
|
+
License, and convey such a combined library under terms of your
|
134
|
+
choice, if you do both of the following:
|
135
|
+
|
136
|
+
a) Accompany the combined library with a copy of the same work based
|
137
|
+
on the Library, uncombined with any other library facilities,
|
138
|
+
conveyed under the terms of this License.
|
139
|
+
|
140
|
+
b) Give prominent notice with the combined library that part of it
|
141
|
+
is a work based on the Library, and explaining where to find the
|
142
|
+
accompanying uncombined form of the same work.
|
143
|
+
|
144
|
+
6. Revised Versions of the GNU Lesser General Public License.
|
145
|
+
|
146
|
+
The Free Software Foundation may publish revised and/or new versions
|
147
|
+
of the GNU Lesser General Public License from time to time. Such new
|
148
|
+
versions will be similar in spirit to the present version, but may
|
149
|
+
differ in detail to address new problems or concerns.
|
150
|
+
|
151
|
+
Each version is given a distinguishing version number. If the
|
152
|
+
Library as you received it specifies that a certain numbered version
|
153
|
+
of the GNU Lesser General Public License "or any later version"
|
154
|
+
applies to it, you have the option of following the terms and
|
155
|
+
conditions either of that published version or of any later version
|
156
|
+
published by the Free Software Foundation. If the Library as you
|
157
|
+
received it does not specify a version number of the GNU Lesser
|
158
|
+
General Public License, you may choose any version of the GNU Lesser
|
159
|
+
General Public License ever published by the Free Software Foundation.
|
160
|
+
|
161
|
+
If the Library as you received it specifies that a proxy can decide
|
162
|
+
whether future versions of the GNU Lesser General Public License shall
|
163
|
+
apply, that proxy's public statement of acceptance of any version is
|
164
|
+
permanent authorization for you to choose that version for the
|
165
|
+
Library.
|
data/Gemfile
ADDED
data/History.md
ADDED
@@ -0,0 +1,124 @@
|
|
1
|
+
0.6.0 / 2016-12-09
|
2
|
+
------------------
|
3
|
+
* Update bundled libusb version to 1.0.21.
|
4
|
+
* Set minimum Ruby version requirement to 1.9.3.
|
5
|
+
* Add binary gems for Linux in addition to Windows.
|
6
|
+
* Switch to mini_portile2 for (cross-) builing the libusb library.
|
7
|
+
* Add Context#interrupt_event_handler new in libusb-1.0.21
|
8
|
+
* Add support for persistent/zerocopy device memory for transfers.
|
9
|
+
It is new in libusb-1.0.21 and enabled by default for DevHandle#*_transfer methods.
|
10
|
+
* Raise a more meaningful exception in case of bulk stream transfers on too old libusb versions.
|
11
|
+
* Prefer the bundled libusb-dll over installed system library.
|
12
|
+
|
13
|
+
0.5.1 / 2015-09-29
|
14
|
+
------------------
|
15
|
+
* Add ability to force use of the system or builtin libusb-1.0 library.
|
16
|
+
Use: gem install libusb -- --enable-system-libusb / --disable-system-libusb
|
17
|
+
* Update to libusb-1.0.20.
|
18
|
+
* Build Windows binary gems per rake-compiler-dock.
|
19
|
+
* Fix memory leak in Context#pollfds and use libusb_free_pollfds() if available.
|
20
|
+
|
21
|
+
0.5.0 / 2015-01-08
|
22
|
+
------------------
|
23
|
+
* Add support for BOS describtors of libusb-1.0.16
|
24
|
+
* Add support for superspeed endpoint companion descriptors of libusb-1.0.16
|
25
|
+
* Add support for USB-3.0 bulk streams of libusb-1.0.19
|
26
|
+
* Update bundled libusb version to 1.0.19.
|
27
|
+
* Update windows cross build to gcc-4.8 and recent rubygems
|
28
|
+
|
29
|
+
0.4.1 / 2014-05-17
|
30
|
+
------------------
|
31
|
+
* Update bundled libusb version to 1.0.18.
|
32
|
+
* Change libusbx references back to libusb, since they have merged again.
|
33
|
+
|
34
|
+
0.4.0 / 2013-11-20
|
35
|
+
------------------
|
36
|
+
* Add support for device hotplug notifications.
|
37
|
+
* Update to libusbx-1.0.17.
|
38
|
+
* Add DevHandle#auto_detach_kernel_driver= of libusb-1.0.16.
|
39
|
+
* Add new capabilities introduced with libusb-1.0.16.
|
40
|
+
* Offer #has_capability? for libusb versions older than 1.0.9.
|
41
|
+
* Add new method port_numbers with alias to port_path.
|
42
|
+
* Use libusb_get_port_numbers preferred to now deprecated libusb_get_port_path.
|
43
|
+
|
44
|
+
0.3.4 / 2013-04-05
|
45
|
+
------------------
|
46
|
+
* Avoid closing of pollfds by the Ruby GC when used as IO object.
|
47
|
+
|
48
|
+
0.3.3 / 2013-04-05
|
49
|
+
------------------
|
50
|
+
* Build and package binary x64 version of libusb for Windows in addition to x86.
|
51
|
+
* Fix build on Windows from source gem (although may take almost an hour).
|
52
|
+
|
53
|
+
0.3.2 / 2013-02-16
|
54
|
+
------------------
|
55
|
+
* Don't enforces DevKit installation on Windows.
|
56
|
+
* Fix error check on libusb_get_device_list(). Thanks to Paul Kunysch for the bug report.
|
57
|
+
* Add support for Cygwin. Requires ffi-1.4.0.
|
58
|
+
|
59
|
+
0.3.1 / 2013-01-22
|
60
|
+
------------------
|
61
|
+
* Fix loading of compiled libusb library on OSX
|
62
|
+
|
63
|
+
0.3.0 / 2013-01-21
|
64
|
+
------------------
|
65
|
+
* Build bundled libusbx sources in case libusb-1.0.so can not be loaded from the system
|
66
|
+
* Replace Hoe with Bundler
|
67
|
+
* Add timeout and completion_flag to Context#handle_events
|
68
|
+
* Add asynchronous DevHandle#{control|interrupt|bulk}_transfer method variants
|
69
|
+
* Add the ability to retrieve the data already transfered when it comes to an exception
|
70
|
+
* Add notification API for libusb's file describtors for event driven USB transfers
|
71
|
+
* Add experimental integration to EventMachine
|
72
|
+
* Add several convenience methods to descriptors
|
73
|
+
* Add missing return code checks to libusb_init() and libusb_get_device_list()
|
74
|
+
|
75
|
+
0.2.2 / 2012-10-19
|
76
|
+
------------------
|
77
|
+
* Add method Interface#bInterfaceNumber
|
78
|
+
* Fix methods (#claim_interface, #detach_kernel_driver) with Interface-type parameter
|
79
|
+
* update to libusbx-1.0.14 for windows build
|
80
|
+
|
81
|
+
0.2.1 / 2012-09-25
|
82
|
+
------------------
|
83
|
+
* Rename Configuration#maxPower to #bMaxPower as done in libusbx-1.0.13 and in ruby-usb.gem
|
84
|
+
* update to libusbx-1.0.13 for windows build (with support for libusbK and libusb0)
|
85
|
+
|
86
|
+
0.2.0 / 2012-06-15
|
87
|
+
------------------
|
88
|
+
* Divide up the libusb library across multiple files, required with autoload
|
89
|
+
* add methods: LIBUSB.has_capability?, Device#device_speed (libusb-1.0.9+)
|
90
|
+
* add possibility to read out libusb version: LIBUSB.version (libusbx-1.0.10+)
|
91
|
+
* add methods: Device#parent, Device#port_number, Device#port_path (libusbx-1.0.12+)
|
92
|
+
* switch to libusbx-1.0.12 for windows build
|
93
|
+
|
94
|
+
0.1.3 / 2012-03-15
|
95
|
+
-------------------
|
96
|
+
* Add documentation of descriptor accessors
|
97
|
+
* Fix #extra accessor of Configuration, Setting and Endpoint
|
98
|
+
|
99
|
+
0.1.2 / 2012-03-14
|
100
|
+
------------------
|
101
|
+
* Mark all blocking functions as blocking in FFI, so that parallel threads are not blocked
|
102
|
+
* Add method Device#open_interface
|
103
|
+
* Add block variant to #claim_interface
|
104
|
+
* update API documentation
|
105
|
+
|
106
|
+
0.1.1 / 2011-12-09
|
107
|
+
------------------
|
108
|
+
* avoid ffi calls with :blocking=>true, als long as it isn't stable on win32
|
109
|
+
|
110
|
+
0.1.0 / 2011-10-01
|
111
|
+
------------------
|
112
|
+
* add test suite based on mass storage devices
|
113
|
+
* usable async transfers
|
114
|
+
* migration to rake-compiler and hoe
|
115
|
+
* cross compiled Windows gems
|
116
|
+
* distinct exception classes
|
117
|
+
* new compatibility layer for ruby-usb.gem
|
118
|
+
* many helper methods for different USB descriptors
|
119
|
+
* add LIBUSB constants
|
120
|
+
* downcase methods names
|
121
|
+
|
122
|
+
0.0.1 / 2009-06-23
|
123
|
+
------------------
|
124
|
+
* first public release
|
data/README.md
ADDED
@@ -0,0 +1,159 @@
|
|
1
|
+
<!-- -*- coding: utf-8 -*- -->
|
2
|
+
|
3
|
+
[![Build Status](https://travis-ci.org/larskanis/libusb.svg)](https://travis-ci.org/larskanis/libusb)
|
4
|
+
[![Build Status](https://ci.appveyor.com/api/projects/status/mdfnfdwu4mil42o3?svg=true)](https://ci.appveyor.com/project/larskanis/libusb)
|
5
|
+
|
6
|
+
Access USB devices from Ruby
|
7
|
+
============================
|
8
|
+
|
9
|
+
LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices.
|
10
|
+
|
11
|
+
* [libusb](http://libusb.info) is a library that gives full access to devices connected via the USB bus. No special kernel driver is thus necessary for accessing USB devices.
|
12
|
+
* This Ruby binding supports the API version 1.0 of [libusb](http://libusb.info). Note that the old "legacy" version 0.1.x of libusb uses a completely different API that is covered by the ruby extension [ruby-usb](http://www.a-k-r.org/ruby-usb/) .
|
13
|
+
|
14
|
+
|
15
|
+
LIBUSB for Ruby is covered by the GNU Lesser General Public License version 3.
|
16
|
+
|
17
|
+
Features
|
18
|
+
--------
|
19
|
+
|
20
|
+
* Access to descriptors of devices, configurations, interfaces, settings and endpoints
|
21
|
+
* Synchronous and asynchronous communication for bulk, control, interrupt and isochronous transfers
|
22
|
+
* Support for USB-3.0 descriptors and bulk streams
|
23
|
+
* Compatibility layer for [ruby-usb](http://www.a-k-r.org/ruby-usb/) (API based on libusb-0.1). See {::USB} for description.
|
24
|
+
|
25
|
+
Synopsis
|
26
|
+
--------
|
27
|
+
```ruby
|
28
|
+
require "libusb"
|
29
|
+
|
30
|
+
usb = LIBUSB::Context.new
|
31
|
+
device = usb.devices(idVendor: 0x04b4, idProduct: 0x8613).first
|
32
|
+
device.open_interface(0) do |handle|
|
33
|
+
handle.control_transfer(bmRequestType: 0x40, bRequest: 0xa0, wValue: 0xe600, wIndex: 0x0000, dataOut: 1.chr)
|
34
|
+
end
|
35
|
+
```
|
36
|
+
{LIBUSB::Context#devices} is used to get all or only particular devices.
|
37
|
+
After {LIBUSB::Device#open_interface opening and claiming} the {LIBUSB::Device} the resulting {LIBUSB::DevHandle} can be
|
38
|
+
used to communicate with the connected USB device
|
39
|
+
by {LIBUSB::DevHandle#control_transfer}, {LIBUSB::DevHandle#bulk_transfer},
|
40
|
+
{LIBUSB::DevHandle#interrupt_transfer} or by using the {LIBUSB::Transfer} classes.
|
41
|
+
|
42
|
+
A {LIBUSB::Device} can also be used to retrieve information about it,
|
43
|
+
by using the device descriptor attributes.
|
44
|
+
A {LIBUSB::Device} could have several configurations. You can then decide of which
|
45
|
+
configuration to enable. You can only enable one configuration at a time.
|
46
|
+
|
47
|
+
Each {LIBUSB::Configuration} has one or more interfaces. These can be seen as functional group
|
48
|
+
performing a single feature of the device.
|
49
|
+
|
50
|
+
Each {LIBUSB::Interface} has at least one {LIBUSB::Setting}. The first setting is always default.
|
51
|
+
An alternate setting can be used independent on each interface.
|
52
|
+
|
53
|
+
Each {LIBUSB::Setting} specifies it's own set of communication endpoints.
|
54
|
+
Each {LIBUSB::Endpoint} specifies the type of transfer, direction, polling interval and
|
55
|
+
maximum packet size.
|
56
|
+
|
57
|
+
See [the documentation](http://rubydoc.info/gems/libusb/frames) for a full API description.
|
58
|
+
|
59
|
+
Prerequisites
|
60
|
+
-------------
|
61
|
+
|
62
|
+
* Linux, MacOS or Windows system with Ruby MRI 1.9/2.x, JRuby or recent version of Rubinius
|
63
|
+
* Optionally: [libusb](http://libusb.info) C-library version 1.0.8 or any newer version.
|
64
|
+
The system libusb library can be installed like so:
|
65
|
+
* Debian or Ubuntu:
|
66
|
+
|
67
|
+
```
|
68
|
+
$ sudo apt-get install libusb-1.0-0-dev
|
69
|
+
```
|
70
|
+
* MacOS: install with homebrew:
|
71
|
+
|
72
|
+
```
|
73
|
+
$ brew install libusb
|
74
|
+
```
|
75
|
+
or macports:
|
76
|
+
|
77
|
+
```
|
78
|
+
$ port install libusb
|
79
|
+
```
|
80
|
+
* Windows: libusb.gem already comes with a precompiled `libusb.dll`, but you need to install a device driver (see [below](#usage-on-windows))
|
81
|
+
|
82
|
+
Install
|
83
|
+
-------
|
84
|
+
|
85
|
+
$ gem install libusb
|
86
|
+
|
87
|
+
While ```gem install``` the system is checked for a usable libusb library installation.
|
88
|
+
If none could be found, a bundled libusb version is built and used, instead.
|
89
|
+
|
90
|
+
Latest code can be used in this way:
|
91
|
+
|
92
|
+
$ git clone git://github.com/larskanis/libusb.git
|
93
|
+
$ bundle
|
94
|
+
$ rake install_gem
|
95
|
+
|
96
|
+
Troubleshooting
|
97
|
+
------------------------
|
98
|
+
In order to implement a driver for a USB device, it's essential to have a look at the packets that are send to and received back from the USB device. [Wireshark](https://www.wireshark.org) has builtin capabilities to sniff USB traffic. On Linux you possibly need to load the usbmon kernel module before start:
|
99
|
+
```
|
100
|
+
sudo modprobe usbmon
|
101
|
+
```
|
102
|
+
On Windows it's possible to sniff USB, if the USB kernel driver was installed by the Wireshark setup.
|
103
|
+
|
104
|
+
![Wireshark](wireshark-usb-sniffer.png?raw=true "Wireshark sniffing USB packets")
|
105
|
+
|
106
|
+
Device hotplug support
|
107
|
+
----------------------
|
108
|
+
|
109
|
+
Support for device hotplugging can be used, if ```LIBUSB.has_capability?(:CAP_HAS_HOTPLUG)``` returns ```true```.
|
110
|
+
This requires libusb-1.0.16 or newer on Linux or MacOS. Windows support is [still on the way](https://github.com/libusbx/libusbx/issues/9).
|
111
|
+
|
112
|
+
A hotplug event handler can be registered with {LIBUSB::Context#on_hotplug_event}.
|
113
|
+
You then need to call {LIBUSB::Context#handle_events} in order to receive any events.
|
114
|
+
This can be done as blocking calls (possibly in it's own thread) or by using {LIBUSB::Context#pollfds} to
|
115
|
+
detect any events to handle.
|
116
|
+
|
117
|
+
|
118
|
+
Usage on Windows
|
119
|
+
----------------
|
120
|
+
|
121
|
+
In contrast to Linux, any access to an USB device by LIBUSB on Windows requires a proper driver
|
122
|
+
installed in the system. Fortunately creating such a driver is quite easy with
|
123
|
+
[Zadig](http://zadig.akeo.ie/). Select the interesting USB device,
|
124
|
+
choose WinUSB driver and press "Install Driver". That's it. You may take the generated output directory
|
125
|
+
with it's INI-file and use it for driver installations on other 32 or 64 bit Windows
|
126
|
+
systems.
|
127
|
+
|
128
|
+
|
129
|
+
Cross compiling for Windows
|
130
|
+
---------------------------
|
131
|
+
|
132
|
+
Libusb-gem can be cross built for Windows and Linux operating systems, using the [rake-compiler-dock](https://github.com/larskanis/rake-compiler-dock) .
|
133
|
+
Just run:
|
134
|
+
|
135
|
+
$ rake gem:native
|
136
|
+
|
137
|
+
If everything works, there are several platform specific gem files (like `libusb-VERSION-x64-mingw32.gem`) in the pkg
|
138
|
+
directory.
|
139
|
+
|
140
|
+
EventMachine integration
|
141
|
+
------------------------
|
142
|
+
|
143
|
+
Libusb for Ruby comes with an experimental integration to [EventMachine](http://rubyeventmachine.com/).
|
144
|
+
That API is currently proof of concept - see {LIBUSB::Context#eventmachine_register}.
|
145
|
+
If you're experienced with EventMachine, please leave a comment.
|
146
|
+
|
147
|
+
|
148
|
+
Resources
|
149
|
+
---------
|
150
|
+
|
151
|
+
* Project's home page: http://github.com/larskanis/libusb
|
152
|
+
* API documentation: http://rubydoc.info/gems/libusb/frames
|
153
|
+
* Mailinglist: http://rubyforge.org/mailman/listinfo/libusb-hackers
|
154
|
+
* Overall introduction to USB: http://www.usbmadesimple.co.uk
|
155
|
+
|
156
|
+
Todo
|
157
|
+
----
|
158
|
+
|
159
|
+
* stabilize EventMachine interface
|