INTRODUCTION

    pyhidapi is a Python binding for the hidapi library, which
    provides a platform-independent interface to USB Human Interface
    Device (HID) hardware from user programs. The hidapi library
    itself is an external dependency and is not included in the
    pyhidapi package. The hidapi library may be found here:

        https://github.com/signal11/hidapi

INSTALLATION

    Use the setup.py script to install pyhidapi. Here are some usage
    examples:

    Install in your user directory:
        ./setup.py install --user

    Install in the system default location:
        sudo ./setup.py install

    Install under /usr/local:
        sudo ./setup.py install --prefix /usr/local

    Create a source distribution:
        ./setup.py sdist

USAGE EXAMPLE

    Here is a simple example, showing how to enumerate all HID devices
    on the system with pyhidapi:

    -------- 8< cut here 8< --------
    #!/usr/bin/env python
    import hidapi

    hidapi.hid_init()
    
    for dev in hidapi.hid_enumerate():
        print '------------------------------------------------------------'
        print dev.description()
    -------- 8< cut here 8< --------


DETAILED DOCUMENTATION
    NAME
        hidapi - Python binding for the hidapi library.
    
    FILE
        hidapi/hidapi.py
    
    DESCRIPTION
        pyhidapi is a Python binding for the hidapi library, which provides a
        platform-independent interface to USB Human Interface Device (HID)
        hardware from user programs. The hidapi library itself is an external
        dependency and is not included in the pyhidapi package. The hidapi
        library may be found here:
        
            https://github.com/signal11/hidapi
        
        Users of this module must call hid_init() before calling any other
        functions defined by the module.
        
        On the Mac, if the hidapi library is installed under /usr/local/lib,
        it may be necessary to set the DYLD_LIBRARY_PATH environment variable
        to '/usr/local/lib' so that find_library() will search there.
        
        Public classes defined by this module:
        
            hid_device_info
        
        Public functions defined by this module:
        
            hid_close(device)
            hid_enumerate(vendor_id=0, product_id=0)
            hid_error(device)
            hid_exit()
            hid_get_feature_report(device, data)
            hid_get_indexed_string(device, string_index)
            hid_get_manufacturer_string(device)
            hid_get_product_string(device)
            hid_get_serial_number_string(device)
            hid_init()
            hid_lib_path()
            hid_open(vendor_id, product_id, serial_number=None)
            hid_open_path(path)
            hid_read(device, length)
            hid_read_timeout(device, length, milliseconds)
            hid_send_feature_report(device, data)
            hid_set_nonblocking(device, nonblock)
            hid_write(device, data)
    
    CLASSES
        __builtin__.object
            hid_device_info
        
        class hid_device_info(__builtin__.object)
         |  Describes an HID device found by hid_enumerate().
         |  
         |  Methods defined here:
         |  
         |  __init__(self, _hid_device_info__hid_device=None)
         |      Constructor for class hid_device_info.
         |      
         |      __hid_device argument is for internal use by this module.
         |  
         |  description(self)
         |      Return a printable string describing the device.
         |  
         |  ----------------------------------------------------------------------
         |  Data descriptors defined here:
         |  
         |  __dict__
         |      dictionary for instance variables (if defined)
         |  
         |  __weakref__
         |      list of weak references to the object (if defined)
         |  
         |  ----------------------------------------------------------------------
         |  Data and other attributes defined here:
         |  
         |  interface_number = 0
         |  
         |  manufacturer_string = u''
         |  
         |  path = ''
         |  
         |  product_id = 0
         |  
         |  product_string = u''
         |  
         |  release_number = 0
         |  
         |  serial_number = u''
         |  
         |  usage = 0
         |  
         |  usage_page = 0
         |  
         |  vendor_id = 0
    
    FUNCTIONS
        hid_close(device)
            Close an HID device.
            
            Arguments:
                device: A device handle returned by hid_open().
            
            Returns:
                None
        
        hid_enumerate(vendor_id=0, product_id=0)
            Enumerate the HID devices.
            
            This function returns a list of hid_device_info objects
            describing all of the HID devices which match vendor_id and product_id.
            If vendor_id is set to the default of 0, then any vendor matches.
            If product_id is set to the default of 0, then any product matches.
            If both are set to the default of 0, then all HID devices will be returned.
            
            Arguments:
                vendor_id:  The 16-bit vendor ID (VID) of devices to be enumerated.
            
                product_id: The 16-bit product ID (PID) of devices to be enumerated.
            
            Returns:
                List of hid_device_info objects, or an empty list.
        
        hid_error(device)
            Get a string describing the last error which occurred.
            
            Arguments:
                device: A device handle returned by hid_open().
            
            Returns:
                String describing the last error that occurred, or None if no
                error has occurred.
        
        hid_exit()
            Clean up hidapi library resources.
            
            Arguments:
                None
            
            Returns:
                None
        
        hid_get_feature_report(device, data)
            Get a feature report from a HID device.
            
            Set the first byte of data[] to the Report ID of the report to be read, and
            make the size of data equal to the size of the desired report plus one more byte
            for the report ID number.
            
            *** This function is not adequately tested, because the author has not yet
            *** identified a device which uses feature reports with which to test the
            *** code.
            
            Arguments:
                device: A device handle returned by hid_open().
            
                data: A bytearray to be sent to the device as the feature report
                      request. Set the first byte to the desired report ID, or
                      0x00 if the device does not use numbered reports.
            
            Returns:
                Bytearray containing report from device. The first byte
                will be the report number.
                Raises RuntimeError exception if an error occurs.
        
        hid_get_indexed_string(device, string_index)
            Get a string from an HID device, based on its string index.
            
            Arguments:
                device: A device handle returned by hid_open().
            
                string_index: String index number to be fetched.
            
            Returns:
                Requested unicode string.
                Raises RuntimeError exception if error occurs.
        
        hid_get_manufacturer_string(device)
            Get the manufacturer string from an HID device.
            
            Arguments:
                device: A device handle returned by hid_open().
            
            Returns:
                Manufacturer unicode string.
                Raises RuntimeError exception if error occurs.
        
        hid_get_product_string(device)
            Get the product string from an HID device.
            
            Arguments:
                device: A device handle returned by hid_open().
            
            Returns:
                Product unicode string.
                Raises RuntimeError exception if error occurs.
        
        hid_get_serial_number_string(device)
            Get the serial number string from an HID device.
            
            Arguments:
                device: A device handle returned by hid_open().
            
            Returns:
                Serial number unicode string.
                Raises RuntimeError exception if error occurs.
        
        hid_init()
            Initialize the hidapi library.
            
            User code must call this function before calling any other functions
            defined by this module.
        
        hid_lib_path()
            Return path of loaded hidapi library.
            
            Arguments:
                none
            
            Returns:
                String containing path of loaded hidapi library.
        
        hid_open(vendor_id, product_id, serial_number=None)
            Open an HID device by its VID and PID.
            
            Specify the desired device by vendor ID (VID), product ID (PID),
            and an optional serial number.
            
            If serial_number is None, open the first device found with the specified
            VID and PID.
            
            Arguments:
                vendor_id:  The 16-bit vendor ID (VID) of the device to be opened.
            
                product_id: The 16-bit product ID (PID) of the device to be opened.
            
                serial_number: Optional serial number Unicode string.
            
            Returns:
                Handle to opened device.
                Raises RuntimeError exception if device cannot be opened.
        
        hid_open_path(path)
            Open an HID device by its path name.
            
            The path name be determined by calling hid_enumerate(), or a
            platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
            
            Arguments:
                path: Path name of the device to open.
            
            Returns:
                Handle to opened device.
                Raises RuntimeError exception if device cannot be opened.
        
        hid_read(device, length)
            Read an Input report from a HID device.
            
            Input reports are returned to the host through the INTERRUPT IN endpoint.
            The first byte will contain the Report number if the device uses numbered
            reports.
            
            Arguments:
                device: A device handle returned by hid_open().
            
                length: Number of bytes to be read. For devices with multiple reports,
                        include an extra byte for the report number.
            
            Returns:
                bytearray containing data that was read.
                Raises RuntimeError exception if an error occurs.
        
        hid_read_timeout(device, length, milliseconds)
            Read an Input report from a HID device with timeout.
            
            Input reports are returned to the host through the INTERRUPT IN endpoint.
            The first byte will contain the Report number if the device uses numbered
            reports.
            
            Arguments:
                device: A device handle returned by hid_open().
            
                length: Number of bytes to be read. For devices with multiple reports,
                        include an extra byte for the report number.
            
                milliseconds: Timeout in milliseconds, or -1 for blocking read.
            
            Returns:
                bytearray containing data that was read.
                If no packet was available to be read within the timeout,
                returns an empty bytearray.
                Raises RuntimeError exception if an error occurs.
        
        hid_send_feature_report(device, data)
            Send a Feature report to the device.
            
            Feature reports are sent over the Control endpoint as a Set_Report
            transfer. The first byte of data[] must contain the Report ID. For
            devices which only support a single report, this must be set to 0x00.
            The remaining bytes contain the report data. Since the Report ID is
            mandatory, calls to hid_send_feature_report() will always contain one
            more byte than the report contains. For example, if a hid report is
            16 bytes long, 17 bytes must be passed to hid_send_feature_report():
            the Report ID (or 0x00, for devices which do not use numbered reports),
            followed by the report data (16 bytes). In this example, the length
            passed in would be 17.
            
            *** This function is not adequately tested, because the author has not yet
            *** identified a device which uses feature reports with which to test the
            *** code.
            
            Arguments:
                device: A device handle returned by hid_open().
            
                data: A bytearray containing the data to be written.
            
            Returns:
                Actual number of bytes written.
                Raises RuntimeError exception if an error occurs.
        
        hid_set_nonblocking(device, nonblock)
            Set the device handle to be non-blocking.
            
            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. Nonblocking can be turned on and off at any time.
            
            Arguments:
                device: A device handle returned by hid_open().
            
                nonblock: Set to True or 1 to enable nonblocking mode.
                          Set to False or 0 to disable nonblocking mode.
            
            Returns:
                None
                Raises RuntimeError exception if error occurs.
        
        hid_write(device, data)
            Write an Output report to a HID device.
            
            The first byte of the data argument  must contain the Report ID. For
            devices which only support a single report, this must be set to 0x00.
            The remaining bytes contain the report data. Since the Report ID is
            mandatory, calls to hid_write() will always contain one more byte
            than the report contains. For example, if a hid report is 16 bytes
            long, 17 bytes must be passed to hid_write(), the Report ID (or 0x00,
            for devices with a single report), followed by the report data (16
            bytes). In this example, the length passed in would be 17.
            
            hid_write() will send the data on the first OUT endpoint, if one
            exists. If it does not, it will send the data through the Control
            Endpoint (Endpoint 0).
            
            Arguments:
                device: A device handle returned by hid_open().
            
                data: A bytearray containing the data to be written.
            
            Returns:
                Actual number of bytes written.
                Raises RuntimeError exception if an error occurs.
    


AUTHOR

     Mark J. Blair, NF6X <nf6x@nf6x.net>

COPYRIGHT

    pyhidapi is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
 
    pyhidapi 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 General Public License for more details.
 
    You should have received a copy of the GNU General Public License
    along with pyhidapi.  If not, see <http://www.gnu.org/licenses/>.