Skip to content

Conversation

aleitner
Copy link
Contributor

@aleitner aleitner commented Aug 20, 2025

This PR adds Web USB API integration to the Guacamole client, enabling users to redirect local USB devices from their browser to remote desktop sessions through the Guacamole protocol. This complements the server-side PR

Each USB device connection creates a ManagedUSB instance that manages the entire lifecycle of that specific device. This handles opening, claiming interfaces, polling endpoints for data, and disconnecting. These are registered with the ManagedClient.

Data Flow

  1. User connects a USB device via Web USB API
  2. ManagedUSB instance is created and added to ManagedClient.usbDevices
  3. Device interfaces are claimed and endpoint polling begins
  4. Incoming USB data is base64-encoded and sent via usbdata messages
  5. Server responses are decoded and written to appropriate USB endpoints
  6. Disconnection can be initiated from either client or server side

New proposed protocol messages

client → server

  • usbconnect: Sent when a USB device is connected, includes device ID, vendor/product IDs, device metadata, and flattened interface/endpoint descriptors
  • usbdata: Streams data from USB device endpoints to the server with endpoint number and transfer type
  • usbdisconnect: Notifies server when a USB device is disconnected locally

server → client

  • usbdata: Receives data from the server to write to specific USB device endpoints
  • usbdisconnect: Server-initiated disconnection requests for specific devices

@necouchman
Copy link
Contributor

@aleitner : GUACAMOLE-2050 was closed as a duplicate of GUACAMOLE-522.

@aleitner aleitner changed the title GUACAMOLE-2050: USB Device Redirection. GUACAMOLE-522: USB Device Redirection. Aug 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants