Recently, OSGi is gaining popularity as an enabling technology for building embedded systems in the residential market as well as other Internet-of-Things (IoT) domains. It is expected that communication with various devices attached to OSGi enabled gateways will be necessary.
Such communication can be implemented by means of serial connection when using non-IP devices based on ZigBee and Z-wave protocols. The most typical case arises when a USB dongle that supports such protocols is connected to the USB port of such a device, for example, residential gateway. The Operating System on the gateways will recognize the dongle as a virtual serial device and initiate a serial communication with the application process.
The Serial Device Service specification defines an API for establishing communications between an OSGi bundle and a serial device, such as a ZigBee coordinator or Z-Wave controller.
Device Category Specifications defines the concept of device categories. USB Information Device Category Specification defines a device category for USB devices. This specification and USB Information Device Category Specification provide a solution for the USB serial use case.
-
SerialDevice - This is an OSGi service that is used to represent a serial device. This OSGi service stores information regarding serial device and its status as service properties and provides communication function with the device.
-
SerialEventListener - A listener to events coming from Serial Devices.
-
Serial base driver bundle - The bundle that implements SerialDevice. Serial base driver bundle registers SerialDevice services with the Framework. It provides communication function with the (physical) serial devices.
-
Refining driver bundle - Refining drivers provide a refined view of a physical device that is already represented by another Device service registered with the Framework (see the details for Device Access Specification).
SerialDevice is the interface expressing a serial device. It
maintains information and state of the serial device as a service
property. It provides the communication facility with the serial device.
Each SerialDevice expresses each serial device.
SerialDevice service is registered with the service
registry with service properties as shown in the following table.
Table 146.1 Service properties of SerialDevice service
| The key of service property | Type | Description |
|---|---|---|
DEVICE_CATEGORY |
String[] |
Constant for the value of the service property DEVICE_CATEGORY used for all Serial devices. Value is "Serial". |
serial.comport |
String |
MANDATORY property key. Represents the name of the port. Examples: "/dev/ttyUSB0", "COM5", "/dev/tty.usbserial-XXXXXX" |
The Serial base driver may need native libraries. This document has a precondition that there are native libraries. It is out of scope how to install native libraries.
Serial events are sent using the white board model, in which a bundle interested in receiving the Serial events registers an object implementing the SerialEventListener interface. A COM port name can be set to limit the events for which a bundle is notified.
The Serial base driver registers a SerialDevice
service that represents a (physical) Serial device. If the device is USB
Serial device, then it is recommended that the base driver implements
USBInfoDevice and SerialDevice concurrently, and
registers the service under USBInfoDevice
and SerialDevice interfaces.
To acquire the Serial device service, the refining bundle need that
ServicePermission[SerialDevice, GET] are assigned.
To receive the Serial events, the bundles need that
ServicePermission[SerialEventListener, REGISTER] are
assigned.
SerialDevice service should only be implemented by
trusted bundles. This bundle requires
ServicePermission[SerialDevice, REGISTER] and
ServicePermission[SerialEventListener, GET].
Serial Device Service 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.serial; version="[1.0,2.0)"
-
SerialConstants- Constants for serial device settings. -
SerialDevice- SerialDevice is a service representing a device performing serial communication. -
SerialDeviceException- A exception used to indicate that a serial device communication problem occurred. -
SerialEvent- A serial device event. -
SerialEventListener- Serial events are sent using the white board model, in which a bundle interested in receiving the Serial events registers an object implementing the SerialEventListener interface. -
SerialPortConfiguration- An object represents the Serial port configuration.
Constants for serial device settings.
SerialDevice is a service representing a device performing serial communication.
Thread-safe
Constant for the value of the service property DEVICE_CATEGORY
used for all Serial devices.
A Serial base driver bundle must set this property key.
Service property for the serial comport.
Represents the name of the port. The value type is String.
For example, "/dev/ttyUSB0", "COM5", or "/dev/tty.usbserial-XXXXXX".
Gets the Serial port configuration.
The SerialPortConfiguration object containing the configuration.
Returns an input stream.
An input stream.
IOException– if an I/O error occurred.
Returns an output stream.
An output stream.
IOException– If an I/O error occurred.
The SerialPortConfiguration object containing the configuration.
Sets the Serial port configuration.
SerialDeviceException– If the parameter is specified incorrectly
or the parameter is not supported.
true for DTR on; false for DTR for off.
Sets the DTR state.
SerialDeviceException– If the parameter is not supported.
A exception used to indicate that a serial device communication problem occurred.
The type for this exception.
The message.
Creates a SerialDeviceException with the specified type and message.
A serial device event. SerialEvent objects are delivered to SerialEventListeners when an event occurs.
A type of code is used to identify the event. Additional event types may be defined in the future.
Thread-safe
Returns the port name of this event.
This value must be equal to the value of SerialDevice.SERIAL_COMPORT service property of the SerialDevice.
The port name of this event.
Serial events are sent using the white board model, in which a bundle interested in receiving the Serial events registers an object implementing the SerialEventListener interface. A COM port name can be set to limit the events for which a bundle is notified.
Thread-safe
Key for a service property that is used to limit received events.
An object represents the Serial port configuration.
Immutable
Baud rate.
Data bits.
Flow control.
Parity.
Stop bits.
Creates an instance of the serial port configuration with the specified Baud rate, Data bits, Flow control, Parity and Stop bits.
Baud rate.
Creates an instance of the serial port configuration with the specified Baud rate and the following configuration: Data bits = 8, Flow control = none, Parity = none, Stop bits = 1.
Creates an instance of the serial port configuration with the following configuration: Baud rate = auto, Data bits = 8, Flow control = none, Parity = none, Stop bits = 1.