Tryanks/gousb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Moar documentation and examples.

Browse Source
This commit is contained in:
Sebastian Zagrodzki
2017-05-06 02:16:53 +02:00
parent eb5500f387
commit 89dc91ef06
2 changed files with 238 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
usb.go
View File

@@ -13,9 +13,109 @@
// See the License for the specific language governing permissions and
// limitations under the License.
// Package gousb provides an low-level interface to attached USB devices.
//
// A Context represents a new
/*
Package gousb provides an low-level interface to attached USB devices.
A Short Tutorial
A Context manages all resources necessary for communicating with USB
devices.
Through the Context users can iterate over available USB devices,
The USB standard defines a mechanism of discovering USB device functionality
through a mechanism of descriptors. After the device is attached and
initialized by the host stack, it's possible to retrieve it's descriptor
(the device descriptor). It contains elements such as product and vendor IDs,
bus number and device number (address) on the bus.
In gousb Device struct represents the USB device, and Device.Descriptor
contains all the information known about the device.
Among other information in the device descriptor is a list of configuration
descriptors, accessible through Device.Descriptor.Configs.
USB standard allows one physical USB device to switch between different
sets of behaviors, or working modes, by selecting one of the offered configs
(each device has at least one).
This allows the same device to sometimes present itself as e.g. a 3G modem,
and sometimes a flash drive. Configs are mutually exclusive, each device
can have only one active config at a time. Switching the active config performs
a light-weight device reset. Each config in the device descriptor has
a unique identification number.
In gousb a device config needs to be selected through Device.Config(num).
It returns a Config struct that represents the device in this particular configuration.
The configuration descriptor is accessible through Config.Info.
A config descriptor determines the list of available USB interfaces on the device.
Each interface is a virtual device within the physical USB device and it's active
config. There can be many interfaces active concurrently. Interfaces are
enumerated sequentially starting from zero.
Additionally, each interface comes with a number of alternate settings for
the interface, which are somewhat similar to device configs, but on the
interface level. Each interface can have only a single alternate setting
active at any time. Alternate settings are enumerated sequentially starting from
zero.
In gousb an interface and it's alternate setting can be selected through
Config.Interface(num, altNum). The Interface struct is the representation
of the claimed interface with a particular alternate setting.
The descriptor of the interface is available through Interface.Setting.
An interface with a particular alternate setting defines up to 15
endpoints. An endpoint can be considered similar to a UDP/IP port,
except the data transfers are unidirectional.
Endpoints are represented by the Endpoint struct, and all defined endpoints
can be obtained through the Endpoints field of the Interface.Setting.
Each endpoint descriptor (EndpointInfo) defined in the interface's endpoint
map includes information about the type of the endpoint:
- endpoint number
- direction: IN (device-to-host) or OUT (host-to-device)
- transfer type: USB standard defines a few distinct data transfer types:
--- bulk - high throughput, but no guaranteed bandwidth and no latency guarantees,
--- isochronous - medium throughput, guaranteed bandwidth, some latency guarantees,
--- interrupt - low throughput, high latency guarantees.
The endpoint descriptor determines the type of the transfer that will be used.
- maximum packet size: maximum number of bytes that can be sent or received by the device in a single USB transaction.
and a few other less frequently used pieces of endpoint information.
An IN Endpoint can be opened for reading through Interface.InEndpoint(epNum),
while an OUT Endpoint can be opened for writing through Interface.OutEndpoint(epNum).
An InEndpoint implements the io.Reader interface, an OutEndpoint implements
the io.Writer interface. Both Reads and Writes will accept larger slices
of data than the endpoint's maximum packet size, the transfer will be split
into smaller USB transactions as needed. But using Read/Write size equal
to an integer multiple of maximum packet size helps with improving the transfer
performance.
Apart from 15 possible data endpoints, each USB device also has a control endpoint.
The control endpoint is present regardless of the current device config, claimed
interfaces and their alternate settings. It makes a lot of sense, as the control endpoint is actually used, among others,
to issue commands to switch the active config or select an alternate setting for an interface.
Control commands are also ofen use to control the behavior of the device. There is no single
standard for control commands though, and many devices implement their custom control command schema.
Control commands can be issued through Device.Control().
See Also
For more information about USB protocol and handling USB devices,
see the excellent "USB in a nutshell" guide: http://www.beyondlogic.org/usbnutshell/
*/
package gousb
// Context manages all resources related to USB device handling.

136
usb_test.go
View File

@@ -15,7 +15,11 @@
package gousb
import "testing"
import (
"fmt"
"log"
"testing"
)
func TestListDevices(t *testing.T) {
_, done := newFakeLibusb()
@@ -84,3 +88,133 @@ func TestOpenDeviceWithVIDPID(t *testing.T) {
}
}
}
// This examples demonstrates the use of a few convenience functions that
// can be used in simple situations and with simple devices.
// It opens a device with a given VID/PID,
// claims the default interface (use the same config as currently active,
// interface 0, alternate setting 0) and tries to write 5 bytes of data
// to endpoint number 7.
func Example_simple() {
// Initialize a new Context.
ctx := NewContext()
defer ctx.Close()
// Open any device with a given VID/PID using a convenience function.
dev, err := ctx.OpenDeviceWithVIDPID(0x046d, 0xc526)
if err != nil {
log.Fatalf("Could not open a device: %v", err)
}
defer dev.Close()
// Claim the default interface using a convenience function.
// The default interface is always #0 alt #0 in the currently active
// config.
intf, err := dev.DefaultInterface()
if err != nil {
log.Fatalf("%s.DefaultInterface(): %v", dev, err)
}
defer intf.Close()
// Open an OUT endpoint.
ep, err := intf.OutEndpoint(7)
if err != nil {
log.Fatalf("%s.OutEndpoint(7): %v", intf, err)
}
// Generate some data to write.
data := make([]byte, 5)
for i := range data {
data[i] = byte(i)
}
// Write data to the USB device.
numBytes, err := ep.Write(data)
if numBytes != 5 {
log.Fatalf("%s.Write([5]): only %d bytes written, returned error is %v", numBytes, err)
}
fmt.Println("5 bytes successfuly sent to the endpoint")
}
// This example demostrates the full API for accessing endpoints.
// It opens a device with a known VID/PID, switches the device to
// configuration #2, in that configuration it opens (claims) interface #3 with alternate setting #0.
// Within that interface setting it opens an IN endpoint number 6 and an OUT endpoint number 5, then starts copying
// data between them,
func Example_complex() {
// Initialize a new Context.
ctx := NewContext()
defer ctx.Close()
// Iterate through available Devices, finding all that match a known VID/PID.
vid, pid := ID(0x04f2), ID(0xb531)
devs, err := ctx.ListDevices(func(desc *Descriptor) bool {
// this function is called for every device present.
// Returning true means the device should be opened.
return desc.Vendor == vid && desc.Product == pid
})
// All returned devices are now open and will need to be closed.
for _, d := range devs {
defer d.Close()
}
if err != nil {
log.Fatalf("ListDevices(): %v", err)
}
if len(devs) == 0 {
log.Fatalf("no devices found matching VID %s and PID %s", vid, pid)
}
// Pick the first device found.
dev := devs[0]
// Switch the configuration to #2.
cfg, err := dev.Config(2)
if err != nil {
log.Fatalf("%s.Config(2): %v", dev, err)
}
defer cfg.Close()
// In the config #2, claim interface #3 with alt setting #0.
intf, err := cfg.Interface(3, 0)
if err != nil {
log.Fatalf("%s.Interface(3, 0): %v", cfg, err)
}
defer intf.Close()
// In this interface open endpoint #6 for reading.
epIn, err := intf.InEndpoint(6)
if err != nil {
log.Fatalf("%s.InEndpoint(6): %v", intf, err)
}
// And in the same interface open endpoint #5 for writing.
epOut, err := intf.OutEndpoint(5)
if err != nil {
log.Fatalf("%s.OutEndpoint(5): %v", intf, err)
}
// Buffer large enough for 10 USB packets from endpoint 6.
buf := make([]byte, 10*epIn.Info.MaxPacketSize)
total := 0
// Repeat the read/write cycle 10 times.
for i := 0; i < 10; i++ {
// readBytes might be smaller than the buffer size. readBytes might be greater than zero even if err is not nil.
readBytes, err := epIn.Read(buf)
if err != nil {
fmt.Println("Read returned an error:", err)
}
if readBytes == 0 {
log.Fatalf("IN endpoint 6 returned 0 bytes of data.")
}
// writeBytes might be smaller than the buffer size if an error occured. writeBytes might be greater than zero even if err is not nil.
writeBytes, err := epOut.Write(buf[:readBytes])
if err != nil {
fmt.Println("Write returned an error:", err)
}
if writeBytes != readBytes {
log.Fatalf("IN endpoint 5 received only %d bytes of data out of %d sent", writeBytes, readBytes)
}
total += writeBytes
}
fmt.Printf("Total number of bytes copied: %d\n", total)
}