145 USB Information Device Category Specification

145.1 Introduction

The Device Access Specification defines a unified and sophisticated way to handle devices attached to a residential gateway or devices found in the home network by using various protocols such as USB, ZigBee, Z-Wave, KNX, UPnP, etc.

Recently, OSGi is gaining popularity as enabling technology for building embedded systems in the residential market as well as other Internet-of-Things (IoT) domains. Such systems often have USB interfaces and the need of handling USB devices attached to these systems is increasing.

Device Category Specifications defines the concept of device categories. This specification defines a device category for USB devices.

145.1.1 Entities

  • USBInfoDevice - The representation of a USB device. This service provide information defined by the USB Implementers Forum, Inc.

Figure 145.1 USB Information Device Service Overview Diagram

USB Information Device Service Overview Diagram

145.2 USBInfoDevice Service

The device services are registered in the OSGi service registry with the USBInfoDevice interface. The service is registered by a USB information base driver bundle when a USB device is attached. A USB information base driver bundle must implement USBInfoDevice interface and register the OSGi service under USBInfoDevice . Refining drivers can find USB devices via USBInfoDevice services and identify the device. The USBInfoDevice service has a set of properties.

USB Specification, see [1] Universal Serial Bus Specification Revision 1.1 , defines that a USB device has USB interface(s). A USB information base driver bundle must register USBInfoDevice services number of USB interfaces. A USBInfoDevice service has information that contains a USB device information and a USB interface information.

The USB information base driver may need native drivers such as kernel drivers on Linux. This document has a precondition that there are native drivers. It is out of scope how to install native drivers.

145.2.1 Device Access Category

The device access category is called "USBInfo". The category name is defined as a value of DEVICE_CATEGORY constant. It must be used as a part of theDEVICE_CATEGORY service property value on the USBInfoDevice service. The category defines the following additional service properties for the USBInfoDevice service.

145.2.2 Service Properties based upon USB Specification

The USB Specification defines a Device Descriptor. USB devices report their attributes using descriptors. The following USBInfoDevice service properties use information from the USB device descriptor.

Table 145.1 Service properties of USBInfoDevice service from Device Descriptor

The key of service property Type Description Device Descriptor's Field from USB Spec.
usbinfo.bcdUSB String

OPTIONAL property key. The 4-digit BCD format.

Example: "0210"

bcdUSB
usbinfo.bDeviceClass String

MANDATORY property key. Hexadecimal, 2-digits.

Example: "ff"

bDeviceClass
usbinfo.bDeviceSubClass String

MANDATORY property key. Hexadecimal, 2-digits.

Example: "ff"

bDeviceSubClass
usbinfo.bDeviceProtocol String

MANDATORY property key. Hexadecimal, 2-digits.

Example: "ff"

bDeviceProtocol
usbinfo.bMaxPacketSize0 Integer

OPTIONAL property key.

bMaxPacketSize0
usbinfo.idVendor String

MANDATORY property key. Hexadecimal, 4-digits.

Example: "0403"

idVendor
usbinfo.idProduct String

MANDATORY property key. Hexadecimal, 4-digits.

Example: "8372"

idProduct
usbinfo.bcdDevice String

MANDATORY property key. The 4-digit BCD format.

Example: "0200"

bcdDevice
usbinfo.Manufacturer String

OPTIONAL property key. String value referenced by iManufacturer. The value is not the index value of iManufacturer.

Example: "Buffalo Inc."

iManufacturer
usbinfo.Product String

OPTIONAL property key. String value referenced by iProduct. The value is not the index value of iProduct.

Example: "USB2.0 PC Camera"

iProduct
usbinfo.SerialNumber String

OPTIONAL property key. String value referenced by iSerialNumber. The value is not the index value of iSerialNumber.

Example: "57B0002600000001"

iSerialNumber
usbinfo.bNumConfigurations Integer

OPTIONAL property key.

bNumConfigurations

According to the USB Specification, a device descriptor has some Interface Descriptors.

Refining drivers need each interface descriptor's bInterfaceClass, bInterfaceSubClass and bInterfaceProtocol to identify devices. The following USBInfoDevice service properties use information from the USB interface descriptor.

Table 145.2 Service properties of USBInfoDevice service from Interface Descriptor

The key of service property Type Description Interface Descriptor's Field from USB Spec.
usbinfo.bInterfaceNumber Integer

MANDATORY property key.

bInterfaceNumber
usbinfo.bAlternateSetting Integer

OPTIONAL property key.

bAlternateSetting
usbinfo.bNumEndpoints Integer

OPTIONAL property key.

bNumEndpoints
usbinfo.bInterfaceClass String

MANDATORY property key. Hexadecimal, 2-digits.

Example: "ff"

bInterfaceClass
usbinfo.bInterfaceSubClass String

MANDATORY property key. Hexadecimal, 2-digits.

Example: "ff"

bInterfaceSubClass
usbinfo.bInterfaceProtocol String

MANDATORY property key. Hexadecimal, 2-digits.

Example: "ff"

bInterfaceProtocol
usbinfo.Interface String

OPTIONAL property key. String value referenced by iInterface. The value is not the index value of iInterface.

iInterface

145.2.3 Additional Service Properties

Some additional service properties are needed to identify and access a device by refining drivers.

Table 145.3 Additional service properties of USBInfoDevice service

The key of service property Type Description
usbinfo.bus Integer

MANDATORY property key. The value is Integer. Used to identify USB devices with same VID / PID. The value is the ID of the USB bus assigned when connecting the USB device. USB bus ID is integer. The USB bus ID does not change while the USB device remains connected.

Example: 3

usbinfo.address Integer

MANDATORY property key. The value is Integer. Used to identify USB devices with same VID / PID. The value is the ID of the USB address assigned when connecting the USB device. USB address is integer in the range 1-127. The USB address does not change while the USB device remains connected.

Example: 2


145.2.4 Match scale

When the driver service is registered by the driver bundle, the Device Manager calls match(ServiceReference) with the argument of the USBInfoDevice service's Service Reference. The driver responds with a match value based on following choices.

145.3 Security

To acquire USB information device service, The refining bundle require that ServicePermission[USBInfoDevice, GET] is assigned.

USBInfoDevice service should only be implemented by trusted bundles. This bundle requires ServicePermission[USBInfoDevice, REGISTER].

145.4 org.osgi.service.usbinfo

Version 1.0

USB Information Device Category Specification Package Version 1.0.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.usbinfo; version="[1.0,2.0)"

Example import for providers implementing the API in this package:

Import-Package: org.osgi.service.usbinfo; version="[1.0,1.1)"

145.4.1 Summary

145.4.2 public interface USBInfoDevice

Represents a USB device. For each USB device, an object is registered with the framework under the USBInfoDevice interface. A USB information base driver must implement this interface.

The values of the USB property names are defined by the USB Implementers Forum, Inc.

Thread-safe

145.4.2.1 public static final String DEVICE_CATEGORY = "USBInfo"

Constant for the value of the service property DEVICE_CATEGORY used for all USB devices.

A USB information base driver bundle must set this property key.

org.osgi.service.device.Constants.DEVICE_CATEGORY

145.4.2.2 public static final int MATCH_CLASS = 10

Device Access match value indicating a match with USB_BDEVICECLASS or a match with USB_BINTERFACECLASS.

145.4.2.3 public static final int MATCH_MODEL = 40

Device Access match value indicating a match with USB_IDVENDOR, and USB_IDPRODUCT.

145.4.2.4 public static final int MATCH_PROTOCOL = 30

Device Access match value indicating a match with USB_BDEVICECLASS, USB_BDEVICESUBCLASS, and USB_BDEVICEPROTOCOL or a match with USB_BINTERFACECLASS , USB_BINTERFACESUBCLASS, and USB_BINTERFACEPROTOCOL.

145.4.2.5 public static final int MATCH_SUBCLASS = 20

Device Access match value indicating a match with USB_BDEVICECLASS, and USB_BDEVICESUBCLASS or a match with USB_BINTERFACECLASS, and USB_BINTERFACESUBCLASS.

145.4.2.6 public static final int MATCH_VERSION = 50

Device Access match value indicating a match with USB_IDVENDOR, USB_IDPRODUCT, and USB_BCDDEVICE.

145.4.2.7 public static final String USB_ADDRESS = "usbinfo.address"

Service property to identify USB address.

Used to identify USB devices with same VID / PID. The value is the ID of the USB address assigned when connecting the USB device. USB address is an integer in the range 1-127 and does not change while the USB device remains connected. The value type is Integer.

145.4.2.8 public static final String USB_BALTERNATESETTING = "usbinfo.bAlternateSetting"

Service property for USB Interface Descriptor field "bAlternateSetting".

The value type is Integer. This service property is optional.

145.4.2.9 public static final String USB_BCDDEVICE = "usbinfo.bcdDevice"

Service property for USB Device Descriptor field "bcdDevice".

The value type is String; the value is in 4-digit BCD format. For example, "0200".

145.4.2.10 public static final String USB_BCDUSB = "usbinfo.bcdUSB"

Service property for USB Device Descriptor field "bcdUSB".

The value type is String; the value is in 4-digit BCD format. For example, "0210". This service property is optional.

145.4.2.11 public static final String USB_BDEVICECLASS = "usbinfo.bDeviceClass"

Service property for USB Device Descriptor field "bDeviceClass".

The value type is String; the value is in 2-digit hexadecimal. For example, "ff".

145.4.2.12 public static final String USB_BDEVICEPROTOCOL = "usbinfo.bDeviceProtocol"

Service property for USB Device Descriptor field "bDeviceProtocol".

The value type is String; the value is in 2-digit hexadecimal. For example, "ff".

145.4.2.13 public static final String USB_BDEVICESUBCLASS = "usbinfo.bDeviceSubClass"

Service property for USB Device Descriptor field "bDeviceSubClass".

The value type is String; the value is in 2-digit hexadecimal. For example, "ff".

145.4.2.14 public static final String USB_BINTERFACECLASS = "usbinfo.bInterfaceClass"

Service property for USB Interface Descriptor field "bInterfaceClass".

The value type is String; the value is in 2-digit hexadecimal. For example, "ff".

145.4.2.15 public static final String USB_BINTERFACENUMBER = "usbinfo.bInterfaceNumber"

Service property for USB Interface Descriptor field "bInterfaceNumber".

The value type is Integer.

145.4.2.16 public static final String USB_BINTERFACEPROTOCOL = "usbinfo.bInterfaceProtocol"

Service property for USB Interface Descriptor field "bInterfaceProtocol".

The value type is String; the value is in 2-digit hexadecimal. For example, "ff".

145.4.2.17 public static final String USB_BINTERFACESUBCLASS = "usbinfo.bInterfaceSubClass"

Service property for USB Interface Descriptor field "bInterfaceSubClass".

The value type is String; the value is in 2-digit hexadecimal. For example, "ff".

145.4.2.18 public static final String USB_BMAXPACKETSIZE0 = "usbinfo.bMaxPacketSize0"

Service property for USB Device Descriptor field "bMaxPacketSize0".

The value type is Integer. This service property is optional.

145.4.2.19 public static final String USB_BNUMCONFIGURATIONS = "usbinfo.bNumConfigurations"

Service property for USB Device Descriptor field "bNumConfigurations".

The value type is Integer. This service property is optional.

145.4.2.20 public static final String USB_BNUMENDPOINTS = "usbinfo.bNumEndpoints"

Service property for USB Interface Descriptor field "bNumEndpoints".

The value type is Integer. This service property is optional.

145.4.2.21 public static final String USB_BUS = "usbinfo.bus"

Service property to identify USB bus.

Used to identify USB devices with same VID / PID. The value is the ID of the USB bus assigned when connecting the USB device. The USB bus ID is an integer and does not change while the USB device remains connected. The value type is Integer.

145.4.2.22 public static final String USB_IDPRODUCT = "usbinfo.idProduct"

Service property for USB Device Descriptor field "idProduct".

The value type is String; the value is in 4-digit hexadecimal. For example, "8372".

145.4.2.23 public static final String USB_IDVENDOR = "usbinfo.idVendor"

Service property for USB Device Descriptor field "idVendor".

The value type is String; the value is in 4-digit hexadecimal. For example, "0403".

145.4.2.24 public static final String USB_INTERFACE = "usbinfo.Interface"

Service property for name referenced by USB Interface Descriptor field "iInterface".

The value type is String. This service property is optional.

145.4.2.25 public static final String USB_MANUFACTURER = "usbinfo.Manufacturer"

Service property for name referenced by USB Device Descriptor field "iManufacturer".

The value type is String. For example, "Buffalo Inc.". This service property is optional.

145.4.2.26 public static final String USB_PRODUCT = "usbinfo.Product"

Service property for name referenced by USB Device Descriptor field "iProduct".

The value type is String. For example, "USB2.0 PC Camera". This service property is optional.

145.4.2.27 public static final String USB_SERIALNUMBER = "usbinfo.SerialNumber"

Service property for name referenced by USB Device Descriptor field "iSerialNumber".

The value type is String. For example, "57B0002600000001". This service property is optional.

145.5 References

[1]Universal Serial Bus Specification Revision 1.1September 23, 1998.