SuperApp:Bluetooth

Referência de API JavaScript para a classe WVBluetooth. Use estas APIs para adicionar suporte a Bluetooth Low Energy (BLE) em aplicativos HTML5 e Miniapps, incluindo solicitação de permissão de Bluetooth, varredura e conexão com dispositivos BLE, além da descoberta de serviços e características.

Todos os métodos seguem a mesma convenção de chamada:

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

O fluxo de trabalho típico de BLE é: solicitar autorização → varrer → parar varredura → conectar → obter serviços → obter características → ler/escrever/inscrever-se → desconectar.

WVBluetooth.requestAuthorization

Solicita permissão de Bluetooth e ativa o adaptador Bluetooth.

Parâmetros de entrada

• Nenhum.

Parâmetros de callback

Parâmetros do callback de sucesso:

• [object] value: Um objeto JSON com o seguinte campo:

  • [string] state: Retorna poweredOn quando o Bluetooth estiver pronto.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

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

WVBluetooth.scan

Inicia a varredura de dispositivos BLE próximos. O evento WV.Event.WVBluetooth.discoverDevice reporta os dispositivos encontrados.

Parâmetros de entrada

• Nenhum.

Parâmetros de callback

Parâmetros do callback de sucesso:

• Nenhum.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

Escuta de eventos

WV.Event.WVBluetooth.discoverDevice: Dispositivo BLE descoberto

Registre este listener de evento antes de chamar scan para receber os dispositivos descobertos.

Parâmetros do evento:

• [string] name: Nome do dispositivo Bluetooth descoberto.

• [string] deviceId: Endereço Bluetooth do dispositivo. Salve este valor, pois ele é necessário para connect, getServices e outras chamadas subsequentes.

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

Interrompe a varredura de dispositivos BLE. Chame este método após encontrar o dispositivo alvo para economizar bateria.

Parâmetros de entrada

• Nenhum.

Parâmetros de callback

Parâmetros do callback de sucesso:

• Nenhum.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

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

WVBluetooth.connect

Conecta-se a um dispositivo BLE pelo endereço Bluetooth.

Parâmetros de entrada

• [string] deviceId: Endereço Bluetooth do dispositivo alvo, obtido no evento discoverDevice.

Parâmetros de callback

Parâmetros do callback de sucesso:

• Nenhum.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

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

Desconecta do dispositivo BLE atualmente conectado. Escute o evento WV.Event.WVBluetooth.GATTServerDisconnected para lidar com quedas inesperadas de conexão.

Parâmetros de entrada

• Nenhum.

Parâmetros de callback

Parâmetros do callback de sucesso:

• Nenhum.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

Escuta de eventos

WV.Event.WVBluetooth.GATTServerDisconnected: Conexão Bluetooth perdida

Este evento dispara quando o servidor GATT se desconecta, seja por uma chamada explícita de disconnect ou devido a uma queda de conexão.

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

Inicia a descoberta de serviços em um dispositivo BLE conectado.

Pré-requisitos

Chame connect com sucesso antes de invocar este método.

Parâmetros de entrada

• [string] deviceId: Endereço Bluetooth do dispositivo conectado.

Parâmetros de callback

Parâmetros do callback de sucesso:

• [boolean] started: true se a descoberta de serviços tiver iniciado com sucesso; false caso contrário.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

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

Recupera todas as características de um serviço especificado em um dispositivo BLE conectado.

Pré-requisitos

Chame connect com sucesso antes de usar este método.

Parâmetros de entrada

• [string] deviceId: Endereço Bluetooth do dispositivo conectado.

  Nota

  Conecte-se ao dispositivo antes de chamar este método.

• [string] serviceId: UUID do serviço.

Parâmetros de callback

Parâmetros do callback de sucesso:

• [object] characteristics: Array de objetos de característica. Cada objeto contém:

  • [string] characteristicId: UUID da característica.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

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

Grava um valor em uma característica de um dispositivo BLE conectado.

Pré-requisitos

• Conecte-se ao dispositivo primeiro.

• Ative as notificações via startNotifications antes de gravar, caso deseje receber o evento characteristicValueChanged como resposta.

• O valor deve ser uma string codificada em Base64.

Parâmetros de entrada

• [string] deviceId: Endereço Bluetooth do dispositivo conectado.

• [string] serviceId: UUID do serviço.

• [string] characteristicId: UUID da característica.

• [string] value: Valor a ser gravado, codificado como string Base64.

  Nota

  O valor deve ser uma string codificada em Base64.

Parâmetros de callback

Parâmetros do callback de sucesso:

• Nenhum.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

Escuta de eventos

WV.Event.WVBluetooth.characteristicValueChanged: Valor da característica alterado

Este evento dispara quando o dispositivo atualiza o valor de uma característica. Requer que startNotifications esteja ativo para a característica.

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

Lê o valor atual de uma característica de um dispositivo BLE conectado.

Pré-requisitos

Chame connect com sucesso antes de usar este método.

Parâmetros de entrada

• [string] deviceId: Endereço Bluetooth do dispositivo conectado.

  Nota

  Conecte-se ao dispositivo antes de chamar este método.

• [string] serviceId: UUID do serviço.

• [string] characteristicId: UUID da característica.

Parâmetros de callback

Parâmetros do callback de sucesso:

• Objeto contendo o valor da característica como string codificada em Base64.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

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

Inscreve-se nas notificações de alteração de valor da característica. Após o sucesso desta chamada, o evento WV.Event.WVBluetooth.characteristicValueChanged dispara sempre que o dispositivo atualizar o valor da característica.

Pré-requisitos

• Conecte-se ao dispositivo primeiro.

Parâmetros de entrada

• [string] deviceId: Endereço Bluetooth do dispositivo conectado.

  Nota

  Conecte-se ao dispositivo antes de chamar este método.

• [string] serviceId: UUID do serviço.

• [string] characteristicId: UUID da característica.

Parâmetros de callback

Parâmetros do callback de sucesso:

• Nenhum.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

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

Cancela a inscrição nas notificações de alteração de valor da característica.

Pré-requisitos

Chame connect e startNotifications antes de invocar este método.

Parâmetros de entrada

• [string] deviceId: Endereço Bluetooth do dispositivo conectado.

  Nota

  Conecte-se ao dispositivo antes de chamar este método.

• [string] serviceId: UUID do serviço.

• [string] characteristicId: UUID da característica.

Parâmetros de callback

Parâmetros do callback de sucesso:

• Nenhum.

Parâmetros do callback de falha:

• [string] msg: Uma mensagem de erro.

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));
}