USBHub API

Version: 1.0.0

Status:

USBHub interface for Thunder framework.

(Defined with IUSBHub in IUSBHub.h)

Introduction

Scope

This document describes purpose and functionality of the USBHub interface (version 1.0.0). It includes detailed specification about its methods provided and notifications sent.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym	Description
API	Application Programming Interface
HTTP	Hypertext Transfer Protocol
JSON	JavaScript Object Notation; a data interchange format
JSON-RPC	A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term	Description
callsign	The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID	Description
HTTP	HTTP specification
JSON-RPC	JSON-RPC 2.0 specification
JSON	JSON specification
Thunder	Thunder API Reference

Description

USBHub JSON-RPC interface.

Methods

The following methods are provided by the USBHub interface:

USBHub interface methods:

Method	Description
devices	Get a string array defning al devices hooked up to this hub
vendorDevices	Get a string array defining all devices hooked up to this hub cmpliant to the given VendorId/ProductId
device	Get the metadata information about the name passed in the paramater

devices ^method

Get a string array defning al devices hooked up to this hub.

Parameters

This method takes no parameters.

Result

Name	Type	M/O	Description
result	array	mandatory	: List of USB devices (deviceName)
result[#]	string	mandatory	...

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.devices"
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    "..."
  ]
}

vendorDevices ^method

Get a string array defining all devices hooked up to this hub cmpliant to the given VendorId/ProductId.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.vendorId	integer	mandatory	...
params.productId	integer	mandatory	...

Result

Name	Type	M/O	Description
result	array	mandatory	: List of USB devices (deviceName)
result[#]	string	mandatory	...

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.vendorDevices",
  "params": {
    "vendorId": 0,
    "productId": 0
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    "..."
  ]
}

device ^method

Get the metadata information about the name passed in the paramater.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.deviceName	string	mandatory	Name of the device

Result

Name	Type	M/O	Description
result	object	mandatory	All the metadata of the requested deviceName device
result.deviceName	string	mandatory	Name of the USB device
result.parentId	integer	mandatory	Parent Node ID of the device
result.status	string	mandatory	Current device status (must be one of the following: STATUS_ACTIVE, STATUS_NO_DEVICE_CONNECTED, STATUS_SELF_POWERED)
result.deviceLevel	integer	mandatory	Device level
result.portNumber	integer	mandatory	Port number of USB on which the device is attached
result.protocol	integer	mandatory	Protocol supported by the device
result.busSpeed	string	mandatory	Speed of the device (must be one of the following: SPEED_FULL, SPEED_HIGH, SPEED_LOW, SPEED_SUPER)
result.serialNumber	string	mandatory	Serial number of the device
result.flags	string	mandatory	Flags of the device (must be one of the following: FLAGS_AVAILABLE, FLAGS_SWITCHABLE)
result.vendorId	integer	mandatory	The vendor Id assigned to this device
result.productId	integer	mandatory	The product Id assigned to this device
result.deviceClass	integer	mandatory	USB class of the device as per USB specificiation
result.deviceSubclass	integer	mandatory	USB sub class of the device as per USB specificiation
result.devicePath	string	mandatory	The path to be used for the USB device ex: /dev/sdX
result.features	integer	mandatory	Features supported by the device - reserved
result.numLanguageIds	integer	mandatory	Number of language ids present on the device
result.productInfo1	object	mandatory	...
result.productInfo1.languageId	integer	mandatory	Language id present on the device
result.productInfo1.serialNumber	string	mandatory	Unicode string representing the serial number of the device
result.productInfo1.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
result.productInfo1.product	string	mandatory	Unicode string representing the product
result.productInfo2	object	mandatory	...
result.productInfo2.languageId	integer	mandatory	Language id present on the device
result.productInfo2.serialNumber	string	mandatory	Unicode string representing the serial number of the device
result.productInfo2.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
result.productInfo2.product	string	mandatory	Unicode string representing the product
result.productInfo3	object	mandatory	...
result.productInfo3.languageId	integer	mandatory	Language id present on the device
result.productInfo3.serialNumber	string	mandatory	Unicode string representing the serial number of the device
result.productInfo3.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
result.productInfo3.product	string	mandatory	Unicode string representing the product
result.productInfo4	object	mandatory	...
result.productInfo4.languageId	integer	mandatory	Language id present on the device
result.productInfo4.serialNumber	string	mandatory	Unicode string representing the serial number of the device
result.productInfo4.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
result.productInfo4.product	string	mandatory	Unicode string representing the product

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.device",
  "params": {
    "deviceName": "..."
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "deviceName": "...",
    "parentId": 0,
    "status": "STATUS_NO_DEVICE_CONNECTED",
    "deviceLevel": 0,
    "portNumber": 0,
    "protocol": 0,
    "busSpeed": "SPEED_FULL",
    "serialNumber": "...",
    "flags": "FLAGS_SWITCHABLE",
    "vendorId": 0,
    "productId": 0,
    "deviceClass": 0,
    "deviceSubclass": 0,
    "devicePath": "...",
    "features": 0,
    "numLanguageIds": 0,
    "productInfo1": {
      "languageId": 0,
      "serialNumber": "...",
      "manufacturer": "...",
      "product": "..."
    },
    "productInfo2": {
      "languageId": 0,
      "serialNumber": "...",
      "manufacturer": "...",
      "product": "..."
    },
    "productInfo3": {
      "languageId": 0,
      "serialNumber": "...",
      "manufacturer": "...",
      "product": "..."
    },
    "productInfo4": {
      "languageId": 0,
      "serialNumber": "...",
      "manufacturer": "...",
      "product": "..."
    }
  }
}

Notifications

Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the USBHub interface:

USBHub interface events:

Notification	Description
announce	Device Plugged in on the bus notification
revoke	Device removed from the bus notification

announce ^notification

Device Plugged in on the bus notification.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.device	object	mandatory	USB information of the plugged in device
params.device.deviceName	string	mandatory	Name of the USB device
params.device.parentId	integer	mandatory	Parent Node ID of the device
params.device.status	string	mandatory	Current device status (must be one of the following: STATUS_ACTIVE, STATUS_NO_DEVICE_CONNECTED, STATUS_SELF_POWERED)
params.device.deviceLevel	integer	mandatory	Device level
params.device.portNumber	integer	mandatory	Port number of USB on which the device is attached
params.device.protocol	integer	mandatory	Protocol supported by the device
params.device.busSpeed	string	mandatory	Speed of the device (must be one of the following: SPEED_FULL, SPEED_HIGH, SPEED_LOW, SPEED_SUPER)
params.device.serialNumber	string	mandatory	Serial number of the device
params.device.flags	string	mandatory	Flags of the device (must be one of the following: FLAGS_AVAILABLE, FLAGS_SWITCHABLE)
params.device.vendorId	integer	mandatory	The vendor Id assigned to this device
params.device.productId	integer	mandatory	The product Id assigned to this device
params.device.deviceClass	integer	mandatory	USB class of the device as per USB specificiation
params.device.deviceSubclass	integer	mandatory	USB sub class of the device as per USB specificiation
params.device.devicePath	string	mandatory	The path to be used for the USB device ex: /dev/sdX
params.device.features	integer	mandatory	Features supported by the device - reserved
params.device.numLanguageIds	integer	mandatory	Number of language ids present on the device
params.device.productInfo1	object	mandatory	...
params.device.productInfo1.languageId	integer	mandatory	Language id present on the device
params.device.productInfo1.serialNumber	string	mandatory	Unicode string representing the serial number of the device
params.device.productInfo1.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
params.device.productInfo1.product	string	mandatory	Unicode string representing the product
params.device.productInfo2	object	mandatory	...
params.device.productInfo2.languageId	integer	mandatory	Language id present on the device
params.device.productInfo2.serialNumber	string	mandatory	Unicode string representing the serial number of the device
params.device.productInfo2.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
params.device.productInfo2.product	string	mandatory	Unicode string representing the product
params.device.productInfo3	object	mandatory	...
params.device.productInfo3.languageId	integer	mandatory	Language id present on the device
params.device.productInfo3.serialNumber	string	mandatory	Unicode string representing the serial number of the device
params.device.productInfo3.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
params.device.productInfo3.product	string	mandatory	Unicode string representing the product
params.device.productInfo4	object	mandatory	...
params.device.productInfo4.languageId	integer	mandatory	Language id present on the device
params.device.productInfo4.serialNumber	string	mandatory	Unicode string representing the serial number of the device
params.device.productInfo4.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
params.device.productInfo4.product	string	mandatory	Unicode string representing the product

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "announce",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.announce",
  "params": {
    "device": {
      "deviceName": "...",
      "parentId": 0,
      "status": "STATUS_NO_DEVICE_CONNECTED",
      "deviceLevel": 0,
      "portNumber": 0,
      "protocol": 0,
      "busSpeed": "SPEED_FULL",
      "serialNumber": "...",
      "flags": "FLAGS_SWITCHABLE",
      "vendorId": 0,
      "productId": 0,
      "deviceClass": 0,
      "deviceSubclass": 0,
      "devicePath": "...",
      "features": 0,
      "numLanguageIds": 0,
      "productInfo1": {
        "languageId": 0,
        "serialNumber": "...",
        "manufacturer": "...",
        "product": "..."
      },
      "productInfo2": {
        "languageId": 0,
        "serialNumber": "...",
        "manufacturer": "...",
        "product": "..."
      },
      "productInfo3": {
        "languageId": 0,
        "serialNumber": "...",
        "manufacturer": "...",
        "product": "..."
      },
      "productInfo4": {
        "languageId": 0,
        "serialNumber": "...",
        "manufacturer": "...",
        "product": "..."
      }
    }
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.announce.

revoke ^notification

Device removed from the bus notification.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.device	object	mandatory	USB information of the plugged in device
params.device.deviceName	string	mandatory	Name of the USB device
params.device.parentId	integer	mandatory	Parent Node ID of the device
params.device.status	string	mandatory	Current device status (must be one of the following: STATUS_ACTIVE, STATUS_NO_DEVICE_CONNECTED, STATUS_SELF_POWERED)
params.device.deviceLevel	integer	mandatory	Device level
params.device.portNumber	integer	mandatory	Port number of USB on which the device is attached
params.device.protocol	integer	mandatory	Protocol supported by the device
params.device.busSpeed	string	mandatory	Speed of the device (must be one of the following: SPEED_FULL, SPEED_HIGH, SPEED_LOW, SPEED_SUPER)
params.device.serialNumber	string	mandatory	Serial number of the device
params.device.flags	string	mandatory	Flags of the device (must be one of the following: FLAGS_AVAILABLE, FLAGS_SWITCHABLE)
params.device.vendorId	integer	mandatory	The vendor Id assigned to this device
params.device.productId	integer	mandatory	The product Id assigned to this device
params.device.deviceClass	integer	mandatory	USB class of the device as per USB specificiation
params.device.deviceSubclass	integer	mandatory	USB sub class of the device as per USB specificiation
params.device.devicePath	string	mandatory	The path to be used for the USB device ex: /dev/sdX
params.device.features	integer	mandatory	Features supported by the device - reserved
params.device.numLanguageIds	integer	mandatory	Number of language ids present on the device
params.device.productInfo1	object	mandatory	...
params.device.productInfo1.languageId	integer	mandatory	Language id present on the device
params.device.productInfo1.serialNumber	string	mandatory	Unicode string representing the serial number of the device
params.device.productInfo1.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
params.device.productInfo1.product	string	mandatory	Unicode string representing the product
params.device.productInfo2	object	mandatory	...
params.device.productInfo2.languageId	integer	mandatory	Language id present on the device
params.device.productInfo2.serialNumber	string	mandatory	Unicode string representing the serial number of the device
params.device.productInfo2.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
params.device.productInfo2.product	string	mandatory	Unicode string representing the product
params.device.productInfo3	object	mandatory	...
params.device.productInfo3.languageId	integer	mandatory	Language id present on the device
params.device.productInfo3.serialNumber	string	mandatory	Unicode string representing the serial number of the device
params.device.productInfo3.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
params.device.productInfo3.product	string	mandatory	Unicode string representing the product
params.device.productInfo4	object	mandatory	...
params.device.productInfo4.languageId	integer	mandatory	Language id present on the device
params.device.productInfo4.serialNumber	string	mandatory	Unicode string representing the serial number of the device
params.device.productInfo4.manufacturer	string	mandatory	Unicode string representing the manufacturer of the device
params.device.productInfo4.product	string	mandatory	Unicode string representing the product

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "revoke",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.revoke",
  "params": {
    "device": {
      "deviceName": "...",
      "parentId": 0,
      "status": "STATUS_NO_DEVICE_CONNECTED",
      "deviceLevel": 0,
      "portNumber": 0,
      "protocol": 0,
      "busSpeed": "SPEED_FULL",
      "serialNumber": "...",
      "flags": "FLAGS_SWITCHABLE",
      "vendorId": 0,
      "productId": 0,
      "deviceClass": 0,
      "deviceSubclass": 0,
      "devicePath": "...",
      "features": 0,
      "numLanguageIds": 0,
      "productInfo1": {
        "languageId": 0,
        "serialNumber": "...",
        "manufacturer": "...",
        "product": "..."
      },
      "productInfo2": {
        "languageId": 0,
        "serialNumber": "...",
        "manufacturer": "...",
        "product": "..."
      },
      "productInfo3": {
        "languageId": 0,
        "serialNumber": "...",
        "manufacturer": "...",
        "product": "..."
      },
      "productInfo4": {
        "languageId": 0,
        "serialNumber": "...",
        "manufacturer": "...",
        "product": "..."
      }
    }
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.revoke.

USBHub API

Table of Contents

Introduction

Scope

Case Sensitivity

Acronyms, Abbreviations and Terms

References

Description

Methods

devices method

Parameters

Result

Example

Request

Response

vendorDevices method

Parameters

Result

Example

Request

Response

device method

Parameters

Result

Example

Request

Response

Notifications

announce notification

Notification Parameters

Example

Registration

Notification

revoke notification

Notification Parameters

Example

Registration

Notification

devices ^method

vendorDevices ^method

device ^method

announce ^notification

revoke ^notification