SuperApp:Bluetooth

JavaScript API reference for the WVBluetooth class. Use these APIs to add Bluetooth Low Energy (BLE) support to HTML5 apps and Miniapps—including requesting Bluetooth permission, scanning for and connecting to BLE devices, and discovering services and characteristics.

All methods follow the same calling convention:

window.WindVane.call('WVBluetooth', '<methodName>', params, successCallback, failureCallback);

The typical BLE workflow is: request authorization → scan → stop scan → connect → get services → get characteristics → read/write/subscribe → disconnect.

WVBluetooth.requestAuthorization

Requests Bluetooth permission and powers on the Bluetooth adapter.

Input parameters

• None.

Callback parameters

Success callback parameters:

• [object] value: A JSON object with the following field:

  • [string] state: Returns poweredOn when Bluetooth is ready.

Failure callback parameters:

• [string] msg: An error message.

window.WindVane.call('WVBluetooth', 'requestAuthorization', {}, function(e) {
        alert('success: ' + JSON.stringify(e));
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
});

WVBluetooth.scan

Starts scanning for nearby BLE devices. Discovered devices are reported through the WV.Event.WVBluetooth.discoverDevice event.

Input parameters

• None.

Callback parameters

Success callback parameters:

• None.

Failure callback parameters:

• [string] msg: An error message.

Event listening

WV.Event.WVBluetooth.discoverDevice: BLE device discovered

Register this event listener before calling scan to receive discovered devices.

Event parameters:

• [string] name: The name of the discovered Bluetooth device.

• [string] deviceId: The Bluetooth address of the device. Save this value—it is required for connect, getServices, and other subsequent calls.

document.addEventListener('WV.Event.WVBluetooth.discoverDevice', function (e) {
        alert('event discoverDevice: ' + JSON.stringify(e.param));
});

window.WindVane.call('WVBluetooth', 'scan', {}, function(e) {
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.stopScan

Stops scanning for BLE devices. Call this after finding your target device to conserve battery.

Input parameters

• None.

Callback parameters

Success callback parameters:

• None.

Failure callback parameters:

• [string] msg: An error message.

window.WindVane.call('WVBluetooth', 'stopScan', {}, function(e) {
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.connect

Connects to a BLE device by its Bluetooth address.

Input parameters

• [string] deviceId: The Bluetooth address of the target device, obtained from the discoverDevice event.

Callback parameters

Success callback parameters:

• None.

Failure callback parameters:

• [string] msg: An error message.

var params = {
  deviceId: '00:aa:bb:cc:dd'
};

window.WindVane.call('WVBluetooth', 'connect', params, function(e) {
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.disconnect

Disconnects from the currently connected BLE device. Listen to the WV.Event.WVBluetooth.GATTServerDisconnected event to handle unexpected connection drops.

Input parameters

• None.

Callback parameters

Success callback parameters:

• None.

Failure callback parameters:

• [string] msg: An error message.

Event listening

WV.Event.WVBluetooth.GATTServerDisconnected: Bluetooth connection lost

This event fires when the GATT server disconnects, either by explicit disconnect call or due to a connection drop.

document.addEventListener('WV.Event.WVBluetooth.GATTServerDisconnected', function (e) {
        alert('event GATTServerDisconnected: ' + JSON.stringify(e.param));
});
window.WindVane.call('WVBluetooth', 'disconnect', {}, function(e) {
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.getServices

Starts service discovery on a connected BLE device.

Prerequisites

Call connect successfully before calling this method.

Input parameters

• [string] deviceId: The Bluetooth address of the connected device.

Callback parameters

Success callback parameters:

• [boolean] started: true if service discovery has started successfully; false otherwise.

Failure callback parameters:

• [string] msg: An error message.

var params = {
  deviceId: '00:aa:bb:cc:dd'
};
window.WindVane.call('WVBluetooth', 'getServices', params, function(e) {
  			alert('success: ' + JSON.stringify(e));
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.getCharacteristics

Retrieves all characteristics for a specified service on a connected BLE device.

Prerequisites

Call connect successfully before calling this method.

Input parameters

• [string] deviceId: The Bluetooth address of the connected device.

  Note

  Connect to the device before calling this method.

• [string] serviceId: The service UUID.

Callback parameters

Success callback parameters:

• [object] characteristics: An array of characteristic objects. Each object contains:

  • [string] characteristicId: The characteristic UUID.

Failure callback parameters:

• [string] msg: An error message.

var params = {
  deviceId: '00:aa:bb:cc:dd',
  serviceId: 'xxxx'
};
window.WindVane.call('WVBluetooth', 'getCharacteristics', params, function(e) {
  			alert('success: ' + JSON.stringify(e));
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.writeValue

Writes a value to a characteristic on a connected BLE device.

Prerequisites

• Connect to the device first.

• Enable notifications via startNotifications before writing if you want to receive the characteristicValueChanged event in response.

• The value must be a Base64-encoded string.

Input parameters

• [string] deviceId: The Bluetooth address of the connected device.

• [string] serviceId: The service UUID.

• [string] characteristicId: The characteristic UUID.

• [string] value: The value to write, encoded as a Base64 string.

  Note

  The value must be a Base64-encoded string.

Callback parameters

Success callback parameters:

• None.

Failure callback parameters:

• [string] msg: An error message.

Event listening

WV.Event.WVBluetooth.characteristicValueChanged: Characteristic value changed

This event fires when the device updates a characteristic value. Requires startNotifications to be active for the characteristic.

document.addEventListener('WV.Event.WVBluetooth.characteristicValueChanged', function (e) {
        alert('event characteristicValueChanged: ' + JSON.stringify(e.param));
});
var params = {
  deviceId: '00:aa:bb:cc:dd',
  serviceId: 'xxxx',
  characteristicId: 'xxx',
  value: 'xxx'
};
window.WindVane.call('WVBluetooth', 'writeValue', params, function(e) {
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.readValue

Reads the current value of a characteristic from a connected BLE device.

Prerequisites

Call connect successfully before calling this method.

Input parameters

• [string] deviceId: The Bluetooth address of the connected device.

  Note

  Connect to the device before calling this method.

• [string] serviceId: The service UUID.

• [string] characteristicId: The characteristic UUID.

Callback parameters

Success callback parameters:

• An object containing the characteristic value as a Base64-encoded string.

Failure callback parameters:

• [string] msg: An error message.

var params = {
  deviceId: '00:aa:bb:cc:dd',
  serviceId: 'xxxx',
  characteristicId: 'xxx'
};
window.WindVane.call('WVBluetooth', 'readValue', params, function(e) {
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.startNotifications

Subscribes to characteristic value change notifications. After this call succeeds, the WV.Event.WVBluetooth.characteristicValueChanged event fires whenever the device updates the characteristic value.

Prerequisites

• Connect to the device first.

Input parameters

• [string] deviceId: The Bluetooth address of the connected device.

  Note

  Connect to the device before calling this method.

• [string] serviceId: The service UUID.

• [string] characteristicId: The characteristic UUID.

Callback parameters

Success callback parameters:

• None.

Failure callback parameters:

• [string] msg: An error message.

var params = {
  deviceId: '00:aa:bb:cc:dd',
  serviceId: 'xxxx',
  characteristicId: 'xxx'
};
window.WindVane.call('WVBluetooth', 'startNotifications', params, function(e) {
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}

WVBluetooth.stopNotifications

Unsubscribes from characteristic value change notifications.

Prerequisites

Call connect and startNotifications before calling this method.

Input parameters

• [string] deviceId: The Bluetooth address of the connected device.

  Note

  Connect to the device before calling this method.

• [string] serviceId: The service UUID.

• [string] characteristicId: The characteristic UUID.

Callback parameters

Success callback parameters:

• None.

Failure callback parameters:

• [string] msg: An error message.

var params = {
  deviceId: '00:aa:bb:cc:dd',
  serviceId: 'xxxx',
  characteristicId: 'xxx'
};
window.WindVane.call('WVBluetooth', 'stopNotifications', params, function(e) {
}, function(e) {
        alert('failure: ' + JSON.stringify(e));
}