Skip to main content
Use this API to listen for changes in the value of a BLE device characteristic. It is triggered when you call my.readBLECharacteristicValue or when a characteristic with notify or indicate enabled pushes a new value.

​
Parameters

PropertyTypeRequiredDescription
callbackFunctionYesCallback when a characteristic value changes

​
Callback Parameters

PropertyTypeDescription
deviceIdStringDevice identifier
serviceIdStringService UUID
characteristicIdStringCharacteristic UUID
valueArrayBufferThe new characteristic value

​
Code Example

​
Basic Usage

my.onBLECharacteristicValueChange((res) => {
  console.log('Device:', res.deviceId);
  console.log('Characteristic:', res.characteristicId);
  console.log('Value:', res.value);
});

​
Read and Handle Value

Page({
  onLoad() {
    my.onBLECharacteristicValueChange(this.handleValueChange);
  },

  handleValueChange(res) {
    // Convert ArrayBuffer to usable data
    const dataView = new DataView(res.value);
    const intValue = dataView.getUint8(0);
    console.log('Received value:', intValue);
    this.setData({ latestValue: intValue });
  },

  readValue() {
    my.readBLECharacteristicValue({
      deviceId: this.data.deviceId,
      serviceId: this.data.serviceId,
      characteristicId: this.data.characteristicId,
    });
  },

  onUnload() {
    my.offBLECharacteristicValueChange(this.handleValueChange);
  }
});

​
Notify-Based Updates

// When characteristic has notify enabled, updates arrive automatically
my.onBLECharacteristicValueChange((res) => {
  if (res.characteristicId === '0000FFF1-0000-1000-8000-00805F9B34FB') {
    const buffer = new Uint8Array(res.value);
    console.log('Sensor data:', Array.from(buffer));
  }
});
The value is delivered as an ArrayBuffer. Use DataView or Uint8Array to interpret the bytes according to the characteristic’s GATT profile.

my.offBLECharacteristicValueChange

Stop listening for value changes

my.readBLECharacteristicValue

Trigger a read on a characteristic

my.getBLEDeviceCharacteristics

Get device characteristics