HyWAI is Hybrid Web Application Platform created by ETRI. Latest version of HyWAI 3.5 can support Bluetooth API for Hybrid Application. HyWAI's Bluetooth APIs is very similar with W3C's Web Bluetooth API. If you have any comment or suggestions, please let me know freely.

1. 2015. 1. 8
HyWAI 3.5 Bluetooth API

2. Table of Contents
Bluetooth API Sequence Diagram
Bluetooth API Comparison Chart1
3
Bluetooth API Web-IDL2

3. W3C Web Bluetooth CG HyWAI 3.5 Bluetooth API
BLE Support O O
BR/EDR Support X Android only1
Pairing/Bonding Process Not specified
Not 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.

4. 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 BluetoothGattServer
instance. 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.

5. 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.

6. 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.

7. 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.

8. 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.

9. 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.

10. 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.

11. 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.

12. 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.

13. II. Bluetooth IDL – BluetoothDescriptor
BluetoothDescriptor 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.

14. II. Bluetooth IDL – CharacteristicProperty
The 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.

15. II. Bluetooth IDL – GattPermission
The 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.

16. 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.

17. 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.

18. 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.

19. 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.

20. II. Bluetooth IDL – BluetoothGattServerCallback
BluetoothGattServerCallback 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.

21. 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.

22. 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.

23. 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.

24. 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.Bluetooth
should 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

25. 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

26. 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

27. 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

28. 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

29. 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. 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 : hollobit@etri.re.kr
 Seungyun Lee (Team Manager)
• Tel:+82-42-860-5508
• Email : syl@etri.re.kr