Moar documentation and examples.

usb.go

@@ -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.
+/*
-//
+Package gousb provides an low-level interface to attached USB devices.
-// A Context represents a new
+
+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.

usb_test.go

@@ -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)
+}