Wiki Navigation

Bluetooth Serial Service

Introduction

The serial service, introduced in the BlueZ 3.10, provides a convenient way for setting up emulated serial cable connections using RFCOMM between two peer devices.

Methods and signals tagged as "experimental" are not available yet. They may be available soon when clear requirements has been defined.

Use Case 1 - Client: Connection creation

Use Case 2 - Server: Serial Proxy

Use Case 3 - Server: Unix socket and localhost

Serial API

The most up-to-date version of the currently implemented serial service D-Bus API can be found in serial/serial-api.txt (bluez-utils source tree).

Temporary Ports

"ConnectService?" method intends to be used as a fast way to connect/create to serial ports. Basically, it triggers a SDP query(if applied, see patterns) and creates a RFCOMM dev node(such as /dev/rfcomm0). Neither SDP query results or dev nodes bindings are stored. RFCOMM dev node lifetime is restricted to the client D-Bus connection, the binding is automatically removed when the connection is closed or the client calls "DisconnectService?".

"ConnectService?" uses the default local adapter, when more than one adapter is available and you wanna address a non-default adapter call ConnectServiceFromAdapter?. The first parameter defines the local adapter address(hcix or xx:xx:xx:xx:xx:xx).

Persistent Ports(Bindings)

"CreatePort?" method shall be used when the remote channel never changes and the client wants store the binding. Bindings are automatically restored when the service starts, bare in mind that id(/dev/rfcommX) can change and there isn't connection status tracking(no signals to notify connection/disconnection). Shortly, "CreatePort?" is a "ConnectService?" with bindings storage.

Accepted Connection Patterns

"ConnectService/CreatePort?" method support severals pattern such as UUID128 string, service record, friendly name and channel.

UUID128 must match with Bluetooth base UUID. Here are some supported examples:

Headset: 00001108-0000-1000-8000-00805F9B34FB
Object push: 00001105-0000-1000-8000-00805F9B34FB

Service records must start at 0x10000 and must be provided in the hexadecimal format.

Channels must be provided using decimal format.

Currently, the supported friendly service names are:

vcp: Video Conference
pbap: Phone Book Access
sap: SIM Access
ftp: OBEX File Transfer
bpp: Printing
bip: Imaging
synch: Synchronization
dun: Dial-Up Networking
opp: OBEX Object Push
fax: Fax
spp: Serial Port
hsp: Headset

Message Flow: ConnectService?

step1: The device discovery procedure may be triggered by the "OBEX Client"
step2: Once the peer address is known, the client can request the serial port creation using the friendly service name or other pattern
step3: When the connection is completed, the serial port device is returned and a D-Bus signal is sent notifying other listeners interested on this signal
step4: Only the owner has permission to request disconnection

Serial Port Proxy

Serial Port Proxy aims provide an easy way to forward data using a Blueototh serial link. Currently the following interfaces are allowed:

Linux I/O device -- eg: "/dev/xxx"
Unix socket -- eg: "00/bluez/echo", "/tmp/gps-data"
Local TCP port -- eg: "localhost:2947"

"CreateProxy?" method has two parameters:

UUID128 string to identify the service
address: device or address to be exported through serial service

If the sun_path starts with a null byte(Unix socket abstract namespaces) "x00" must be added at the beginning of the address to represent the null byte.

When the port proxy is enabled and an incoming connection arrives, the serial service connects automatically to the proxy source(I/O device, Unix socket or Localhost) and forward the raw data through the serial link.

Security

When calling "ConnectService?" a link key can be requested by some remote device. In this case the "ConnectService?" request will wait the bonding procedure. The serial service has no control of this background procedure. If the bonding fails, "ConnectionCanceled?" error is replied.