Android BLE GATT写入返回GATT_SUCCESS但外设未收到数据

核心问题1：写入类型与特征支持的属性不匹配（出现概率90%以上） #

代码里硬编码writeType = WRITE_TYPE_DEFAULT是最常见的诱因：

• WRITE_TYPE_DEFAULT对应需要外设返回ACK的写请求，要求目标特征必须持有PROPERTY_WRITE属性
• 如果你操作的特征实际仅支持无响应写入（PROPERTY_WRITE_NO_RESPONSE），大部分国内厂商定制的安卓BLE栈不会返回参数错误，反而会直接触发onCharacteristicWrite回调返回GATT_SUCCESS，但数据根本没有被提交到射频层发送，外设自然收不到
• 通用BLE工具（比如测试用的BLE Scanner）不会硬编码写入类型，会自动读取特征的properties字段匹配对应的writeType，所以不会触发这个问题。

修复逻辑：写入前动态判断特征支持的写入属性，不要硬编码writeType：

val writeType = when {
    characteristic.properties and BluetoothGattCharacteristic.PROPERTY_WRITE != 0 -> 
        BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
    characteristic.properties and BluetoothGattCharacteristic.PROPERTY_WRITE_NO_RESPONSE != 0 -> 
        BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE
    else -> {
        Log.e(TAG, "当前特征不支持写入操作")
        return
    }
}

核心问题2：旧版BLE写入API的已知缺陷 #

当前使用的setValue() + 单参数writeCharacteristic()是API 33前的废弃接口，存在多个已知问题：

1. 带String参数的setValue()重载会在UTF-8编码的字节末尾自动追加0x00空终止符，如果外设协议不识别带终止符的payload会直接丢弃数据
2. 接口本身没有原子性保障：调用setValue只是修改特征对象的本地缓存，如果在系统取走发送数据前有其他操作修改了该特征的value，会导致实际发送的数据异常
3. 当BLE操作队列拥塞时，writeCharacteristic()会返回false代表请求未被系统受理，但部分厂商系统仍会错误触发onCharacteristicWrite返回成功，误导上层逻辑

修复方案：做API版本兼容，校验接口返回值，手动处理字符串转字节逻辑：

fun writeCharacteristic(characteristic: BluetoothGattCharacteristic, value: String) {
    val gatt = bluetoothGatt ?: run {
        Log.w(TAG, "BluetoothGatt not initialized")
        return
    }
    // 手动转字节，避免系统自动追加空终止符
    val payload = value.toByteArray(Charsets.UTF_8)
    // 动态匹配写入类型
    val writeType = when {
        characteristic.properties and BluetoothGattCharacteristic.PROPERTY_WRITE != 0 -> BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
        characteristic.properties and BluetoothGattCharacteristic.PROPERTY_WRITE_NO_RESPONSE != 0 -> BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE
        else -> {
            Log.e(TAG, "特征不支持写入")
            return
        }
    }

    val writeRequestAccepted = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        // API33+ 使用新接口，直接传入payload，不需要修改特征本地对象
        gatt.writeCharacteristic(characteristic, payload, writeType) == BluetoothStatusCodes.SUCCESS
    } else {
        // 低版本兼容：设置参数后立刻发起写入，中间不要插入任何其他操作
        characteristic.writeType = writeType
        characteristic.value = payload
        gatt.writeCharacteristic(characteristic)
    }

    if (!writeRequestAccepted) {
        Log.e(TAG, "写入请求未被系统接受，无需等待回调，直接按失败逻辑重入队列")
        // 在这里加入失败重试/队列重入逻辑
    }
}

其他必做排查项 #

• 检查串行队列逻辑：安卓BLE栈为单线程模型，必须等上一个GATT操作（读、写、MTU协商、开关通知、修改连接优先级）的对应回调执行完成后，才能发起下一个操作，靠固定延时触发下一个操作的队列逻辑必然会出现随机丢操作的问题。
• 主动协商MTU：服务发现完成后立刻调用bluetoothGatt.requestMtu(512)，等onMtuChanged回调返回实际协商的MTU值后再开始数据收发，避免因为payload长度超过单包上限被系统丢弃。
• 确认特征实例有效性：必须使用bluetoothGatt.services中遍历获取的特征实例发起写入，不要使用服务发现阶段缓存的旧特征对象。

内容的提问来源于stack exchange，提问作者santiago