devices Endpoint¶

The devices endpoint provides a list of all USB devices attached to the host system, including device information, port path, capabilities, and mappings to Acroname devices.

There are no input parameters to this endpoint. It will return a JSON array of devices, encapsulated in a transaction envelope.

JSON Schema for Response Object¶

The following table lists a JSON Schema for the response object.

Download the raw JSON Schema file for this response: devices_response.json

Object Fields of Devices Response¶

Name	Type	Mandatory	Description
`usb`	Array<Object>	Yes	An array containing all USB devices in the system

Object Fields of `usb[]`¶

Name	Type	Mandatory	Description
`vendorId`	v1-vidPid	Yes	Vendor Identifier
`productId`	v1-vidPid	Yes	Product Identifier
`speedActual`	v1-speed	Yes	Current enumerated speed
`maxSpeed`	v1-speed	Yes	Maximum supported speed
`serialNumber`	v1-name	Yes	Vendor-provided serial number
`manufacturer`	v1-name	Yes	Vendor-provided manufacturer name
`productName`	v1-name	Yes	Vendor-provided product name
`deviceClass`	v1-classCode	Yes	Device Class Code
`interfaces`	Array<Object>	Yes	List of all interfaces provided by device
`portPath`	Array<v1-uint8>	Yes	List of the logical IDs of each parent node, starting with the controller ID and followed by the port ID for each parent device.
`acronameDevice`	Object	No	If an Acroname device is detected in this device’s parent tree, information about the Acroname device.
`bulkCapability`	v1-capability	Yes	Capability information for Bulk Transfers
`isochronousCapability`	v1-capability	Yes	Capability information for Isochronous Transfers
`interruptCapability`	v1-capability	Yes	Capability information for Interrupt Transfers

Object Fields of `usb[].interfaces[]`¶

Name	Type	Mandatory	Description
`interfaceIndex`	v1-uint8	Yes	Interface Index within this device
`entryIndex`	v1-uint8	Yes	Alternate Setting Index within this interface
`kClass`	v1-classCode	Yes	USB-IF class code for this interface
`kSubclass`	v1-classCode	Yes	USB-IF subclass code for this interface, qualified by the kClass code
`kProtocol`	v1-uint8	Yes	USB-IF protocol code for this interface, qualified by the kClass and kSubclass codes

Object Fields of `usb[].acronameDevice`¶

Name	Type	Mandatory	Description
`serialNumber`	v1-serialNumber	Yes	Acroname Serial Number
`port`	v1-uint8	Yes	Physical port number on the Acroname device
`distance`	v1-uint8	Yes	Number of parent tiers between Acroanme device and this device

v1-vidPid¶

Name	Value
Type	string
description	Representation of a USB Device or Vendor ID
Regular Expression	`^(0x)?[A-Fa-f0-9]{4}$`

v1-serialNumber¶

Name	Value
Type	string
description	Representation of an Acroname device serial number
Regular Expression	`^(0x)?[A-Fa-f0-9]{8}$`

v1-speed¶

Name	Value
Type	string
description	Enumeration of all possible USB speeds
Enumerations	`Unknown`, `1.5 Mbps`, `12 Mbps`, `480 Mbps`, `5 Gbps`, `10 Gbps`

v1-name¶

Name	Value
Type	string
description	USB-IF Compliant Name Field
Maximum # of Glyphs	`126`

v1-classCode¶

Name	Value
Type	integer
description	Enumeration of all possible USB device/interface classes (https://vovkos.github.io/doxyrest/samples/libusb/enum_libusb_class_code.html)
Enumerations	`0`, `1`, `2`, `3`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `13`, `14`, `15`, `220`, `224`, `254`, `255`

v1-uint8¶

Name	Value
Type	integer
description	Unsigned 8-bit integer
minimum	0
maximum	255

v1-capability¶

Name	Value
Type	Object
description	Description for a capability of a device

Name	Type	Mandatory	Description
`isDoing`	boolean	Yes	Whether the device is currently using this capability
`isCapable`	boolean	Yes	Whether the device is capable of using this capability

v1-aErr¶

Name	Value
Type	string
description	Enumeration of all possible error results
Enumerations	`aErrNone`, `aErrMemory`, `aErrParam`, `aErrNotFound`, `aErrFileNameLength`, `aErrBusy`, `aErrIO`, `aErrMode`, `aErrWrite`, `aErrRead`, `aErrEOF`, `aErrNotReady`, `aErrPermission`, `aErrRange`, `aErrSize`, `aErrOverrun`, `aErrParse`, `aErrConfiguration`, `aErrTimeout`, `aErrInitialization`, `aErrVersion`, `aErrUnimplemented`, `aErrDuplicate`, `aErrCancel`, `aErrPacket`, `aErrConnection`, `aErrIndexRange`, `aErrShortCommand`, `aErrInvalidEntity`, `aErrInvalidOption`, `aErrResource`, `aErrMedia`, `aErrAsyncReturn`, `aErrOperation`, `aErrUnknown`

v1-error¶

Name	Value
Type	Object
description	Error containing an acroname error

Name	Type	Mandatory	Description
`errorCode`	v1-aErr	Yes	Acroname error code
`errorMessage`	string	No	A human-readable message to describe the context of the error.

Examples¶

curl http://127.0.0.1:9005/api/v1/devices

import requests
import json
response = requests.get('http://127.0.0.1:9005/api/v1/devices')
json_data = response.json()
print(json.dumps(json_data, indent=4))

The output will be similar to the following:

{
    "timestamp": "2023-09-20T17:36:15.359Z",
    "request": {
        "endpointName": "/api/v1/devices",
        "parameters": {}
    },
    "response": {
        "usb": [
            {
                "vendorId": "0x067B",
                "productId": "0x2303",
                "speedActual": "12 Mbps",
                "maxSpeed": "12 Mbps",
                "productName": "USB-Serial Controller",
                "serialNumber": "",
                "manufacturer": "Prolific Technology Inc.",
                "deviceClass": 0,
                "interfaces": [
                    {
                        "interfaceIndex": 0,
                        "entryIndex": 0,
                        "kClass": 255,
                        "kSubclass": 0,
                        "kProtocol": 0
                    }
                ],
                "portPath": [
                    4,
                    3,
                    1
                ],
                "acronameDevice": {
                    "serialNumber": "0xF7D9AFB6",
                    "port": 0,
                    "distance": 0
                },
                "bulkCapability": {
                    "isDoing": true,
                    "isCapable": true
                },
                "isochronousCapability": {
                    "isDoing": false,
                    "isCapable": false
                },
                "interruptCapability": {
                    "isDoing": true,
                    "isCapable": true
                }
            },
            {
                "vendorId": "0x2188",
                "productId": "0x0747",
                "speedActual": "5 Gbps",
                "maxSpeed": "5 Gbps",
                "productName": "Card Reader ",
                "serialNumber": "000000000010",
                "manufacturer": "CalDigit",
                "deviceClass": 0,
                "interfaces": [
                    {
                        "interfaceIndex": 0,
                        "entryIndex": 0,
                        "kClass": 8,
                        "kSubclass": 6,
                        "kProtocol": 80
                    }
                ],
                "portPath": [
                    4,
                    8
                ],
                "bulkCapability": {
                    "isDoing": true,
                    "isCapable": true
                },
                "isochronousCapability": {
                    "isDoing": false,
                    "isCapable": false
                },
                "interruptCapability": {
                    "isDoing": false,
                    "isCapable": false
                }
            }
        ]
    }
}