Server Socket API#

The server accepts JSON requests on a TCP socket (default port 5055) and returns JSON responses.

Connection#

The server listens on TCP port 5055 by default on all interfaces (0.0.0.0).

import socket

# Connect to the server
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(("server_hostname", 5055))

Request Formats#

List Request#

Request a list of all available USB devices on the server:

{
  "command": "list"
}

Fields:

  • command: Must be "list"

Device Request#

Request to find, attach, or detach a specific USB device:

{
  "command": "attach",
  "id": "1-1.4",
  "bus": null,
  "serial": null,
  "desc": null,
  "first": false
}

Fields:

  • command: Either "find", "attach", or "detach" (required)

  • id: Bus ID of the device (e.g., “1-1.4”)

  • bus: Bus number filter

  • serial: Serial number filter

  • desc: Description filter (substring match)

  • first: If true, use first matching device if multiple matches

You must provide at least one of: id, bus, serial, or desc to identify the device.

Commands:

  • "find": Locate a device without attaching or detaching it

  • "attach": Bind the device to usbip for sharing (makes it available for client attachment)

  • "detach": Unbind the device from usbip (makes it unavailable for sharing)

Response Formats#

List Response#

{
  "status": "success",
  "data": [
    {
      "bus_id": "1-1.4",
      "device_id": "vid=0x1234 pid=0x5678",
      "description": "Arduino Uno"
    },
    {
      "bus_id": "1-1.5",
      "device_id": "vid=0x2341 pid=0x0043",
      "description": "Arduino Mega"
    }
  ]
}

Fields:

  • status: Always "success" for successful list operations

  • data: Array of USB device objects

    • bus_id: The USB bus ID on the server

    • device_id: Vendor and product IDs

    • description: Human-readable device description

Device Response#

{
  "status": "success",
  "data": {
    "bus_id": "1-1.4",
    "device_id": "vid=0x1234 pid=0x5678",
    "description": "Arduino Uno"
  }
}

Fields:

  • status: "success" for successful operations, "failure" for failed operations

  • data: The USB device information

    • bus_id: The USB bus ID on the server

    • device_id: Vendor and product IDs

    • description: Human-readable device description

Error Response#

{
  "status": "error",
  "message": "Error description"
}

Status values:

  • "error": General error (invalid request, command execution error, etc.)

  • "not_found": No device matching the criteria was found

  • "multiple_matches": Multiple devices matched and first was not set to true

Usage Examples#

Using netcat#

List all devices:

echo '{"command":"list"}' | nc server_hostname 5055

Find a device by description:

echo '{"command":"find","desc":"Arduino","first":true}' | nc server_hostname 5055

Attach a device (make it available for sharing):

echo '{"command":"attach","id":"1-1.4"}' | nc server_hostname 5055

Detach a device (make it unavailable for sharing):

echo '{"command":"detach","id":"1-1.4"}' | nc server_hostname 5055

Using Python#

import json
import socket

def send_request(host: str, port: int, request: dict) -> dict:
    """Send a request to the server and return the response."""
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.connect((host, port))

    # Send request
    sock.sendall(json.dumps(request).encode() + b'\n')

    # Receive response
    response = sock.recv(4096).decode()
    sock.close()

    return json.loads(response)

# List all devices
response = send_request("server_hostname", 5055, {"command": "list"})
if response["status"] == "success":
    print("Available devices:")
    for device in response["data"]:
        print(f"  - {device['description']} ({device['bus_id']})")

# Attach a device
response = send_request(
    "server_hostname",
    5055,
    {"command": "attach", "desc": "Arduino", "first": True}
)
if response["status"] == "success":
    print(f"Attached device: {response['data']['description']}")
    print(f"Bus ID: {response['data']['bus_id']}")
else:
    print(f"Error: {response['message']}")

# Detach a device
response = send_request(
    "server_hostname",
    5055,
    {"command": "detach", "id": "1-1.4"}
)
if response["status"] == "success":
    print(f"Detached device: {response['data']['description']}")

Using curl (with socat)#

You can use socat to create a bridge between HTTP and the TCP socket for testing:

# Terminal 1: Start socat bridge
socat TCP-LISTEN:8080,reuseaddr,fork TCP:server_hostname:5055

# Terminal 2: Send requests via HTTP
curl -X POST http://localhost:8080 -d '{"command":"list"}'
curl -X POST http://localhost:8080 -d '{"command":"attach","desc":"Arduino","first":true}'

See Also#