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.
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.
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.
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 |
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 |
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.
-
MATCH_VERSION - Constant for the USB device match scale, indicating a match with USB_IDVENDOR, USB_IDPRODUCT and USB_BCDDEVICE. Value is 50.
-
MATCH_MODEL - Constant for the USB device match scale, indicating a match with USB_IDVENDOR and USB_IDPRODUCT. Value is 40.
-
MATCH_PROTOCOL - Constant for the USB device match scale, indicating a match with USB_BDEVICECLASS, USB_BDEVICESUBCLASS and USB_BDEVICEPROTOCOL, or a match with USB_BINTERFACECLASS, USB_BINTERFACESUBCLASS and USB_BINTERFACEPROTOCOL. Value is 30.
-
MATCH_SUBCLASS - Constant for the USB device match scale, indicating a match USB_BDEVICECLASS and USB_BDEVICESUBCLASS, or a match with USB_BINTERFACECLASS and USB_BINTERFACESUBCLASS. Value is 20.
-
MATCH_CLASS - Constant for the USB device match scale, indicating a match with USB_BDEVICECLASS, or a match with USB_BINTERFACECLASS. Value is 10.
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].
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)"
-
USBInfoDevice- Represents a USB device.
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
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.
Device Access match value indicating a match with USB_BDEVICECLASS or a match with USB_BINTERFACECLASS.
Device Access match value indicating a match with USB_IDVENDOR, and USB_IDPRODUCT.
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.
Device Access match value indicating a match with USB_BDEVICECLASS, and USB_BDEVICESUBCLASS or a match with USB_BINTERFACECLASS, and USB_BINTERFACESUBCLASS.
Device Access match value indicating a match with USB_IDVENDOR, USB_IDPRODUCT, and USB_BCDDEVICE.
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.
Service property for USB Interface Descriptor field "bAlternateSetting".
The value type is Integer. This service property is optional.
Service property for USB Device Descriptor field "bcdDevice".
The value type is String; the value is in 4-digit BCD format. For example, "0200".
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.
Service property for USB Device Descriptor field "bDeviceClass".
The value type is String; the value is in 2-digit hexadecimal. For example, "ff".
Service property for USB Device Descriptor field "bDeviceProtocol".
The value type is String; the value is in 2-digit hexadecimal. For example, "ff".
Service property for USB Device Descriptor field "bDeviceSubClass".
The value type is String; the value is in 2-digit hexadecimal. For example, "ff".
Service property for USB Interface Descriptor field "bInterfaceClass".
The value type is String; the value is in 2-digit hexadecimal. For example, "ff".
Service property for USB Interface Descriptor field "bInterfaceNumber".
The value type is Integer.
Service property for USB Interface Descriptor field "bInterfaceProtocol".
The value type is String; the value is in 2-digit hexadecimal. For example, "ff".
Service property for USB Interface Descriptor field "bInterfaceSubClass".
The value type is String; the value is in 2-digit hexadecimal. For example, "ff".
Service property for USB Device Descriptor field "bMaxPacketSize0".
The value type is Integer. This service property is optional.
Service property for USB Device Descriptor field "bNumConfigurations".
The value type is Integer. This service property is optional.
Service property for USB Interface Descriptor field "bNumEndpoints".
The value type is Integer. This service property is optional.
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.
Service property for USB Device Descriptor field "idProduct".
The value type is String; the value is in 4-digit hexadecimal. For example, "8372".
Service property for USB Device Descriptor field "idVendor".
The value type is String; the value is in 4-digit hexadecimal. For example, "0403".
Service property for name referenced by USB Interface Descriptor field "iInterface".
The value type is String. This service property is optional.
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.
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.