HyWAI Web Bluetooth API

2015. 1. 8

HyWAI 3.5 Bluetooth API

Table of Contents

Bluetooth API Sequence Diagram

Bluetooth API Comparison Chart1

3

Bluetooth API Web-IDL2

W3C Web Bluetooth CG HyWAI 3.5 Bluetooth API

BLE Support O O

BR/EDR Support X Android only1

Pairing/Bonding Process Not specifiedNot specified

(handled by native OS)

LE Message Reception JavaScript promises Callback functions

LE Message Transmission GATT attribute methods GATT attribute methods

BR/EDR Communication Utilizes BLE interface Socket based communication

Exception Handling Only outlines general guidelines Callback functions

BLE Peripheral Support X iOS only1

BR/EDR Server Support X Android only1

I. Comparison of HyWAI Bluetooth API and W3C Web Bluetooth CG

3

1These operations are defined HyWAI 3.5 API, yet limitations are imposed by respective native operating systems.

II. Bluetooth IDL – hywai.Bluetooth

Methods• getDefaultAdapter

• Returns default BluetoothAdapter instance for this device.• isLeEnabled

• Checks if Bluetooth Low Energy is enabled by current device.• isBrEdrEnabled

• Checks if BR/EDR is enabled by current device.• openServer

• Opens Bluetooth BR/EDR Server with given name and UUID. Returns BluetoothServer instance.• openGattServer

• Opens Bluetooth GATT Server and calls OnGattServerOpenCallback with new BluetoothGattServerinstance. Parameter GattServerCallback object receives remote messages via its callback attributes.

hywai.Bluetooth is HyWAI’s Bluetooth module object which serves as an entry point for all Bluetooth related operations including Bluetooth availability check, BluetoothAdapter retrieval, and server (BR/EDR and BLE) operations.

II. Bluetooth IDL – BlutoothAdapter

BluetoothAdapter, returned by hywai.Bluetooth object, is a singleton object responsible for Bluetooth peripheral discovery with given options and filters.

Methods• startDiscovery

• Starts to discover Bluetooth peripheral devices in range. Devices are filtered by given uuids, and OnDeviceFoundCallback is called with BluetoothDevice object whenever a device is discovered.

• stopDiscovery• Stops discovery. As discovery operations are energy-intensive, this method should be called as

soon as desired device has been discovered.

II. Bluetooth IDL – BluetoothDiscoveryOption

The BluetoothDiscoveryOption enumeration gives users a standardized way to specify types of Bluetooth devices to discover.

Enumeration Description

BLE Discover only Bluetooth Low Energy devices.

CLASSIC Discover only Bluetooth BR/EDR devices.

ALL Discover both Bluetooth LE and BR/EDR devices.

II. Bluetooth IDL – BluetoothDevice (1/2)BluetoothDevice represents a peripheral or central Bluetooth Device object. It outlines device-related operations such as connection (BLE and BR/EDR) and various information access.

Methods• getType

• Returns a long representing the type of this device. (0 – Unknown, 1 – BR/EDR, 2 – BLE, 3 – DUAL) • getName

• Returns human-friendly name of this device.• getDeviceId

• Returns a uniquely assigned id for this device.• getUuids

• Returns UUIDs advertised by this device. This method only works with devices discovered through BR/EDR discovery.

II. Bluetooth IDL – BluetoothDevice (2/2)

Methods

• getServices• If cached is true, gets cached GATT services. Otherwise, fetches GATT services from remote device.

Calls OnServicesGetCallback with BluetoothService objects representing retrieved services.• readRssi

• Reads RSSI value of this device and calls OnRssiReadCallback with retrieved value.• getConnectionState

• Calls OnConnectionStateCallback with device’s connection state. (0 – disconnected, 1 – connecting, 2 – connected, 3 – disconnecting)

• createSocket• Creates a Bluetooth socket with given UUID for BR/EDR communication and calls

OnSocketCreateCallback with BluetoothSocket object. BluetoothSocket, at return, is not connected and BluetoothSocket#connect should be explicitly called to initiate a connection.

• connectGatt• Connects to the device using BLE for GATT interaction. Calls OnSuccessCallback upon successful

connection.• disconnectGatt

• Disconnects from the device’s GATT properties.

II. Bluetooth IDL – BluetoothService (1/2)BluetoothService represents remote device’s GATT service. It contains methods for retrieving its attributes, included services, and characteristics. If created by user for GATT peripheral server operation, it can add characteristics and included services to itself.

Methods• getId

• Returns this service’s unique identifier. • getUuid

• Returns this service’s UUID.• isPrimary

• Returns whether this service is primary.• getIncludedServices

• Calls OnIncludedServicesGetCallback with this service’s included services filtered by given UUIDs. If cached is true, returns cached services. Otherwise, fetches services from remote.

II. Bluetooth IDL – BluetoothService (2/2)

Methods

• getCharacteristics• Calls OnCharacteristicsGetCallback with this service’s characteristics filtered by given UUIDs. If

cached is true, returns cached characteristics. Otherwise, fetches characteristics from remote.• addCharacteristic

• Adds a GATT characteristic represented as BluetoothCharacteristic object to this service and returns OnSuccessCallback if successful. Only accessible if object is created by user via constructor.

• addIncludedService• Adds a GATT service represented as BluetoothService object to this service as included service

and returns OnSuccessCallback if successful. Only accessible if object is created by user via constructor.

II. Bluetooth IDL – BluetoothCharacteristic (1/2)BluetoothCharacteristic represents remote device’s GATT characteristic. It contains methods for retrieving its attributes, reading/writing values and subscribing for notifications. If created by user for GATT peripheral server operation, it can add descriptors to itself.

II. Bluetooth IDL – BluetoothCharacteristic (2/2)Methods• getId

• Returns this characteristic’s unique identifier. • getUuid

• Returns this characteristic’s UUID.• setValue

• Set’s this characteristic’s local value.• getPermissions

• Calls OnGattPermissionsGetCallback with this characteristic’s GATT permissions.• getProperties

• Calls OnCharacteristicPropertiesGetCallback with this characteristic’s properties.• getDescriptors

• Calls OnDescriptorsGetCallback with this characteristic’s descriptors filtered by given UUIDs. If cached is true, returns cached descriptors. Otherwise, fetches descriptors from remote.

• readValue• Calls OnCharacteristicValueReadCallback with this characteristic’s value. If cached is true, returns

cached value. Otherwise, fetches value from remote.• writeValue

• Writes given value to remote and calls OnCharacteristicValueWriteCallback with written value.• startNotification

• Starts to notification for it’s value from remote device. OnCharacteristicvalueNotificationCallback is called with new value whenever a notification is received from remote.

• stopNotification• Stops notification for this characteristic’s value.

• getService• Calls OnServiceGetCallback with this characteristic’s GATT service.

• addDescriptor• Adds a GATT descriptor represented as BluetoothDescriptor object to this characteristic and

returns OnSuccessCallback if successful. Only accessible if object is created by user via constructor.

II. Bluetooth IDL – BluetoothDescriptorBluetoothDescriptor represents remote device’s GATT descriptor. It contains methods for retrieving its attributes and reading/writing values.

Methods• getId

• Returns this descriptor’s unique identifier. • getUuid

• Returns this descriptor’s UUID.• getPermissions

• Calls OnCharacteristicGetCallback with this descriptor’s GATT characteristic.• setValue

• Set’s this characteristic’s local value.• readValue

• Calls OnDescriptorValueReadCallback with this descriptor’s value. If cached is true, returns cached value. Otherwise, fetches value from remote.

• writeValue• Writes given value to remote and calls OnDescriptorValueWriteCallback with written value.

II. Bluetooth IDL – CharacteristicPropertyThe CharacteristicProperty enumeration allows users to use standardized GATT characteristic property by name instead of using platform-specific bitwise operations.

Enumeration Description

PROPERTY_BROADCAST Characteristic is broadcastable.

PROPERTY_EXTENDED_PROPS Characteristic has extended properties.

PROPERTY_INDICATE Characteristic supports indication.

PROPERTY_INDICATE_ENCRYPTED Characteristic supports encrypted indication.

PROPERTY_NOTIFY Characteristic supports notification.

PROPERTY_NOTIFY_ENCRYPTED Characteristic supports encrypted notification.

PROPERTY_READ Characteristic is readable

PROPERTY_SIGNED_WRITE Characteristic supports write with signature.

PROPERTY_WRITE Characteristic can be written.

PROPERTY_WRITE_NO_RESPONSE Characteristic can be written without response.

II. Bluetooth IDL – GattPermissionThe GattPermission enumeration allows users to use standardized GATT permissions by name instead of using platform-specific bitwise operations.

Enumeration Description

PERMISSION_READ Characteristic read permission.

PERMISSION_READ_ENCRPYTED Allow encrypted read operations.

PERMISSION_READ_ENCRPYTED_MITM Allow reading with man-in-the-middle protection

PERMISSION_WRITE Characteristic write permission.

PERMISSION_WRITE_ENCRPYTED Allow encrypted writes.

PERMISSION_WRITE_ENCRPYTED_MITM Allow encrypted writes with man-in-the-middle protection.

PERMISSION_WRITE_SIGNED Allow signed write operations.

PERMISSION_WRITE_SIGNED_MITM Allow signed writes with man-in-the-middle protection.

II. Bluetooth IDL – BluetoothSocket (1/2)BluetoothSocket represents a socket connection between two Bluetooth devices. It contains methods for handling connections, retrieving connection information, and reading/writing data.

Methods• getSocketId

• Gets the unique identifier associated with this socket.• connect

• Establishes a connection. Calls OnSocketConnectedCallback with connected socket object (this).• isConnected

• Calls OnSocketConnectionStateCallback with current connection state. Returns true if connected.• close

• Closes connection and calls OnSuccessCallback if successful.• startReadData

• Starts to read data from this socket. OnDataReceiveCallback is called with value whenever data is received through the socket.

II. Bluetooth IDL – BluetoothSocket (2/2)

Methods

• stopReadData• Stops reading data from this socket.

• writeData• Writes given data to the socket. Calls OnSocketWriteDataCallback with length of data written.

• getDevice• Calls OnDeviceGetCallback with BluetoothDevice object representing the Bluetooth device

associated with this socket.

II. Bluetooth IDL – BluetoothGattServer (1/2)BluetoothGattServer represents current device as a Bluetooth Peripheral in BLE mode. It contains methods to modify it’s server internals, advertise, send notifications, and send response to read/write requests.

Methods• addService

• Adds a GATT service to this server.• removeService

• Removes a GATT service from this server.• clearServices

• Removes all GATT services from this server.• getServices

• Calls OnServicesGetCallback with GATT services added to this server.

II. Bluetooth IDL – BluetoothGattServer (2/2)

Methods

• startAdvertising• Start advertising this server with given device name and service UUIDs. Calls

OnAdvertisementStartCallback with advertisement data• stopAdvertising

• Stops advertising this server.• isAdvertising

• Calls OnAdvertisementStateGetCallback with boolean indicating whether this server is currently advertising.

• sendCharacteristicNotification• Sends characteristic notifications to given Bluetooth devices for given characteristic and value.

Calls OnSuccessCallback after sending notification.• sendResponse

• Sends response to a read/write request for given Bluetooth device and request identifier with given value.

• close• Closes this GATT server.

II. Bluetooth IDL – BluetoothGattServerCallbackBluetoothGattServerCallback contains Bluetooth GATT server callback functions as it’s attributes. These callback function attributes, implemented by user, are called whenever GATT server related events occur. These events include Characteristic subscription and unsubscription, service addition, and characteristic read/write request.

Attributes• onCharacteristicSubscribe

• Callback function called when a central device subscribes to this server’s characteristic.• onCharacteristicUnsubscribe

• Callback function called when a central device unsubscribes from this server’s characteristic.• onServiceAdded

• Callback function called when a GATT service is successfully added to this server.• onCharacteristicReadRequest

• Callback function called when a central device requests to read given characteristic’s value.• onCharacteristicWriteRequest

• Callback function called when a central device requests to write value to given characteristic.• onReadyToUpdateSubscribers

• Callback function called when this server is ready to send notifications to subscribed centrals after previous attempt so send notifications.

II. Bluetooth IDL – BluetoothServer

BluetoothServer represents current device acting as Bluetooth BR/EDR server. It has methods to listen and stop listening to incoming connections.

Methods• listen

• Starts to listen to incoming connections. Calls OnDeviceConnectedCallback with a connected BluetoothSocket object whenever a device is connected to this server.

• close• Stops listening to incoming connections.

III. Bluetooth API Sequence Diagram – BLE Central Role Overview (1/2)

W3C Web Bluetooth CG Specifications• W3C Web Bluetooth CG suggests mandating the user to initiate device discovery with a limited

set of target UUIDs, therefore only exposing relevant devices for intended use.• Each operation is initiated by objects representing respective GATT attributes.• W3C Web Bluetooth CG only specifies API for BLE operations as a central role.

III. Bluetooth API Sequence Diagram – BLE Central Role Overview (2/2)

HyWAI 3.5 Bluetooth API• HyWAI 3.5 Bluetooth API imposes same security obligations as W3C Web Bluetooth CG does.• HyWAI specifically designates BluetoothAdapter object for starting/stopping device discovery.• Device discovery in HyWAI offers options to choose types (BLE, BR/EDR, or both) of target

devices.

III. Bluetooth API Sequence Diagram – BLE Central Role Discovery

W3C Web Bluetooth CG Specifications

• W3C Web Bluetooth only outlines general procedures for device discovery, where HyWAI 3.5 Bluetooth API specifies that BluetoothAdapter object retrieved from global hywai.Bluetoothshould perform device discovery.

• HyWAI 3.5 Bluetooth API allows users to stop discovery at will.• HyWAI 3.5 Bluetooth API uses callback functions for retrieving discovered devices.

HyWAI 3.5 Bluetooth API

III. Bluetooth API Sequence Diagram – BLE Central Role Connection

W3C Web Bluetooth CG Specifications

• W3C Web Bluetooth CG primarily uses Promises to handle asynchronous operations where HyWAI 3.5 Bluetooth API uses user-supplied callback functions.

• Unlike W3C Web Bluetooth CG, HyWAI 3.5 Bluetooth API offers BR/EDR operations, thus specifying “Gatt” to indicate that the operations are BLE-specific.

HyWAI 3.5 Bluetooth API

III. Bluetooth API Sequence Diagram – BLE Central Role Communication

• HyWAI 3.5 Bluetooth API allows users to decide whether to fetch values and GATT attributes from remote or to retrieve them from local caches.

W3C Web Bluetooth CG Specifications HyWAI 3.5 Bluetooth API

III. Bluetooth API Sequence Diagram – BLE Peripheral Role

• W3C Web Bluetooth CG does not specify any API for BLE peripheral role.• HyWAI 3.5 API supports BLE peripheral role using BluetoothGattServer object for server

operations (advertisement, outgoing messages) and GattServerCallback object for incoming requests and callbacks.

HyWAI 3.5 Bluetooth API

III. Bluetooth API Sequence Diagram – BR/EDR Client Role

• W3C Web Bluetooth CG does not specify any API for BR/EDR related operations.• HyWAI 3.5 API supports BR/EDR client role operations using socket-based communication.• HyWAI 3.5 API uses BluetoothSocket objects for any read/write operations with remote server

devices.

HyWAI 3.5 Bluetooth API

III. Bluetooth API Sequence Diagram – BR/EDR Server Role

• W3C Web Bluetooth CG does not specify any API for BR/EDR related operations.• HyWAI 3.5 API supports BR/EDR server role operations using socket-based communication.• HyWAI 3.5 API uses BluetoothSocket objects for any read/write operations with remote client

devices.

HyWAI 3.5 Bluetooth API

30

Contact

HyWAI is Hybrid Web Application Interface Platform

If you have any questions and suggestions, please contact us. Jonghong Jeon (Principal Researcher)

• Tel: +82-42-860-5333• Email : [email protected]

Seungyun Lee (Team Manager)• Tel:+82-42-860-5508• Email : [email protected]