Pike USB Module (Public.USB)
============================

This is a Pike module that provides an interface to the libusb-1.0 library,
enabling USB device communication from Pike programs.


Features
--------

* Full libusb-1.0 API coverage
* Device enumeration and descriptor access
* Synchronous and asynchronous I/O
* USB control, bulk, and interrupt transfers
* Pike backend integration for automatic async event processing
* Vendor ID lookup from usb.ids database


Quick Start
-----------

Basic device enumeration:

    object usb = Public.USB.USB();
    array devices = usb->get_device_list();
    
    foreach(devices, object dev) {
        mapping desc = dev->get_descriptor();
        write("Device: %04x:%04x\n", desc->idVendor, desc->idProduct);
    }


Backend Integration (Async I/O)
--------------------------------

For automatic async transfer completion without manual polling:

    object usb = Public.USB.USB();
    usb->enable_backend_events(1);  // Enable backend integration
    
    // Now async transfers complete automatically when Pike's backend runs
    // (e.g., when main() returns -1 to enter async mode)

How it works:
- Registers USB context with Pike's backend system
- Backend callback pumps USB events non-blockingly every 20ms
- Transfer completion callbacks fire automatically
- No manual handle_events_timeout() calls needed

When to use:
- Pike programs running in asynchronous mode (return -1 from main)
- Applications needing automatic async transfer completion
- Programs integrating USB with Pike's event loop

When NOT to use:
- Synchronous Pike programs (default mode)
- When you want full control over event processing timing
- Testing/debugging scenarios requiring manual event polling

Default: Backend integration is DISABLED. You must explicitly enable it
per USB instance.


Manual Event Processing
-----------------------

For synchronous programs or when you want control over event timing:

    object usb = Public.USB.USB();
    
    // Poll for events manually
    usb->handle_events_timeout(0);     // Non-blocking
    usb->handle_events_timeout(100);   // Wait up to 100ms

This is the traditional approach and remains fully supported.


Vendor ID Lookup
----------------

Get vendor names from USB vendor ID:

    string vendor = Public.USB.get_vendor_name(0x046d);
    // Returns: "Logitech, Inc."

The module includes a usb.ids database for vendor/device name lookups.
Update the database with: make update-usb-ids


Building
--------

    pike -x module          # Build
    pike -x module verify   # Run tests
    make update-usb-ids     # Update USB ID database


Requirements
------------

* Pike 7.6.0 or later (tested with Pike 8.0)
* libusb-1.0 development libraries
* Standard autoconf/automake toolchain


Documentation
-------------

See AGENTS.md for detailed module development information and backend
integration architecture.

Full API documentation is available via Pike's autodoc system:
    pike -x module --autoconf
    make -f Makefile.refdoc module_modref


License
-------

GPL/LGPL/MPL (tri-licensed)