hid

README

This package is discontinued This package does not work with Go1.6+. I won't be updating this package since a better alternative is already available, please take a look at karalabe/hid.

go.hid

This go package wraps the signal11/hidapi and provides communication with USB Human Interface Devices.

This package is not completely tested yet!

Installation:

This project depends on libhidapi, which must be installed manually.

git clone git@github.com:signal11/hidapi.git
cd hidapi
./bootstrap
./configure

Now change directory depending on your OS.

For linux + hidraw: cd linux. (requires libudev. Package libudev-dev on debian/ubuntu.)

For linux + libusb: cd libusb. (requires libusb. Package libusb-1.0-0-dev on debian/ubuntu.)

For mac: cd mac.

For windows: cd windows.

Make and install. For linux/mac:

make
sudo make install

For windows:

run some wizzard, probably.. (PR on readme is very welcome)

Lastly, for linux only: Create a symlink pointing libhidapi.so to the version you chose:

For linux + hidraw: cd /usr/local/lib; sudo ln -s libhidapi-hidraw.so libhidapi.so

For linux + libusb: cd /usr/local/lib; sudo ln -s libhidapi-libusb.so libhidapi.so

For more instructions on libhidapi, please visit signal11/hidapi.

When you have installed hidapi lib, install this package with go get github.com/GeertJohan/go.hid.

Documentation:

godoc.org/github.com/GeertJohan/go.hid

Example:

This is a simple example on how to use feature reports. For a working example view GeertJohan/mgl.

package main

import(
	"log"
	"github.com/GeertJohan/go.hid"
)

func main() {
	// open the MSI GT leds device
	leds, err := hid.Open(0x1770, 0xff00, "")
	if err != nil {
		log.Fatalf("Could not open leds device: %s", err)
	}
	defer leds.Close()

	// create a feature report. This is always 8*n+1 bytes long, where n is >1.
	data := make([]byte, 9)
	data[0] = 0x42  // report ID
	data[1] = 0x00  // dummy data
	data[2] = 0x01  // dummy data
	data[3] = 0x02  // dummy data
	data[4] = 0x03  // dummy data
	data[5] = 0x04  // dummy data
	data[6] = 0x05  // dummy data
	data[7] = 0x06  // dummy data
	data[8] = 0x07  // dummy data

	_, err := leds.SendFeatureReport(data)
	if err != nil {
		log.Fatalf("Could not send feature report to do dummy action. %s\n", err)
	}
}

License:

The go code in this project is licenced under a a Simplified BSD license. Please read the LICENSE file.

TODO:

At this point, the package works for linux with hidraw. hidapi itself is already cross-platform, so making this package work cross-platform shouldn't be a lot of work.

• Make this package work cross-platform.
• Add better support for hidapi init() and exit(). (At this time hidapi's init() is called once on first Open() call)
• Add tests (find if there is a usb-hid dummy device that has expected input/output and works consistently within an OS (we can write a test file for each OS seperated))
• Better example (preferably with a dummy test device)

History:

I started this project to be able to communicate with the MSI leds device in the MSI GT780DX laptop. For more information about that project, visit GeertJohan/mgl.

Documentation

Index

• func Exit() error
• type Device
  • func Open(vendorId uint16, productId uint16, serialNumber string) (*Device, error)
  • func OpenPath(path string) (*Device, error)
  • func (dev *Device) Close()
  • func (dev *Device) GetFeatureReport(reportId byte, reportDataSize int) ([]byte, error)
  • func (dev *Device) GetIndexedString(index int) (string, error)
  • func (dev *Device) ManufacturerString() (string, error)
  • func (dev *Device) ProductString() (string, error)
  • func (dev *Device) Read(b []byte) (n int, err error)
  • func (dev *Device) ReadTimeout(b []byte, timeout int) (n int, err error)
  • func (dev *Device) SendFeatureReport(data []byte) (int, error)
  • func (dev *Device) SerialNumberString() (string, error)
  • func (dev *Device) SetReadWriteNonBlocking(nonblocking bool) error
  • func (dev *Device) Write(b []byte) (n int, err error)
• type DeviceInfo
  • func (di *DeviceInfo) Device() (*Device, error)
• type DeviceInfoList
  • func Enumerate(vendorId uint16, productId uint16) (DeviceInfoList, error)

Functions

func Exit

func Exit() error

TODO

Types

type Device

type Device struct {
	// contains filtered or unexported fields
}

struct hid_device_; typedef struct hid_device_ hid_device; /**< opaque hidapi structure */

func Open

func Open(vendorId uint16, productId uint16, serialNumber string) (*Device, error)

Open HID by vendorId, productId and serialNumber. SerialNumber is optional and can be empty string (""). Returns a *Devica and an error.

func OpenPath

func OpenPath(path string) (*Device, error)

Open hid by path. Returns a *Device and an error

func (*Device) Close

func (dev *Device) Close()

Close the device handle

func (*Device) GetFeatureReport

func (dev *Device) GetFeatureReport(reportId byte, reportDataSize int) ([]byte, error)

Get a FeatureReport from the HID device

func (*Device) GetIndexedString

func (dev *Device) GetIndexedString(index int) (string, error)

Get a string by index. String length will be max 256 wchars.

func (*Device) ManufacturerString

func (dev *Device) ManufacturerString() (string, error)

Get manufacturer string from device

func (*Device) ProductString

func (dev *Device) ProductString() (string, error)

Get product string from device

func (*Device) Read

func (dev *Device) Read(b []byte) (n int, err error)

Read data from HID Implementing the io.Reader interface with this method.

func (*Device) ReadTimeout

func (dev *Device) ReadTimeout(b []byte, timeout int) (n int, err error)

Read from hid device with given timeout

func (*Device) SendFeatureReport

func (dev *Device) SendFeatureReport(data []byte) (int, error)

Send a feature report

func (*Device) SerialNumberString

func (dev *Device) SerialNumberString() (string, error)

Get Serial number string from device

func (*Device) SetReadWriteNonBlocking

func (dev *Device) SetReadWriteNonBlocking(nonblocking bool) error

In non-blocking mode calls to hid_read() will return immediately with a value of 0 if there is no data to be read. In blocking mode, hid_read() will wait (block) until there is data to read before returning.

func (*Device) Write

func (dev *Device) Write(b []byte) (n int, err error)

Write data to hid device. Implementing the io.Writer interface with this method.

type DeviceInfo

type DeviceInfo struct {
	Path            string
	VendorId        uint16
	ProductId       uint16
	SerialNumber    string
	ReleaseNumber   uint16
	Manufacturer    string
	Product         string
	UsagePage       uint16 // Only being used with windows/mac, which are not supported by go.hid yet.
	Usage           uint16 // Only being used with windows/mac, which are not supported by go.hid yet.
	InterfaceNumber int
}

DeviceInfo provides all information about an HID device.

func (*DeviceInfo) Device

func (di *DeviceInfo) Device() (*Device, error)

Get actual hid *Device from DeviceInfo object

type DeviceInfoList

type DeviceInfoList []*DeviceInfo

List of DeviceInfo objects

func Enumerate

func Enumerate(vendorId uint16, productId uint16) (DeviceInfoList, error)

Retrieve a list of DeviceInfo objects that match the given vendorId and productId. To retrieve a list of all HID devices': use 0x0 as vendorId and productId.