Android Kotlin BLE中setValue写入特征失败，如何获取错误原因？

嘿，作为刚踩过Android蓝牙GATT坑的开发者，太懂你这种写入失败却摸不到原因的抓狂了！先给你明确说：特征写入失败是可以获取错误原因的，只是你找错了地方——直接调用setValue本身只负责设置本地特征数据，真正的写入操作结果和错误原因要通过异步回调来获取。

下面一步步给你拆解怎么排查和获取错误：

1. 先搞懂setValue和writeCharacteristic的区别 #

setValue(payload)这个方法的返回值只是告诉你「是否成功把数据设置到本地的BluetoothGattCharacteristic对象里」，它不涉及和远程蓝牙设备的通信。如果它返回false，大概率是以下原因：

• 该特征的属性是只读的（没有PROPERTY_WRITE或PROPERTY_WRITE_NO_RESPONSE权限）
• 你传入的数据格式和特征指定的类型不匹配（比如特征对应整型UUID，你传了字节数组）

你可以先在调用setValue后做个检查：

private fun writeMyCharacteristic(characteristic: BluetoothGattCharacteristic, gatt: BluetoothGatt?) {
    val payload = BluetoothUtils.packagePayload()
    val isSetValueSuccess = characteristic.setValue(payload)
    if (!isSetValueSuccess) {
        // 先排查本地设置失败的原因
        val properties = characteristic.properties
        when {
            (properties and BluetoothGattCharacteristic.PROPERTY_WRITE == 0) && 
            (properties and BluetoothGattCharacteristic.PROPERTY_WRITE_NO_RESPONSE == 0) -> {
                mClientActionListener.log(TAG_GATT, "错误：该特征不支持写入操作")
            }
            else -> {
                mClientActionListener.log(TAG_GATT, "错误：设置特征值失败，数据格式不匹配")
            }
        }
        return
    }
    // 本地设置成功，发起真正的写入请求
    val isWriteInitiated = gatt?.writeCharacteristic(characteristic) ?: false
    if (!isWriteInitiated) {
        mClientActionListener.log(TAG_GATT, "错误：无法发起写入请求，GATT连接可能已断开")
    }
}

2. 通过BluetoothGattCallback获取远程写入的错误原因 #

真正的写入操作是异步的，writeCharacteristic只是发起请求，结果会通过你初始化BluetoothGatt时传入的BluetoothGattCallback回调返回。你必须重写onCharacteristicWrite方法，这里的status参数就是判断错误原因的关键：

private val gattCallback = object : BluetoothGattCallback() {
    // 其他回调方法（比如onConnectionStateChange、onServicesDiscovered）...

    override fun onCharacteristicWrite(
        gatt: BluetoothGatt?,
        characteristic: BluetoothGattCharacteristic?,
        status: Int
    ) {
        super.onCharacteristicWrite(gatt, characteristic, status)
        if (status == BluetoothGatt.GATT_SUCCESS) {
            mClientActionListener.log(TAG_GATT, "特征写入成功🎉")
        } else {
            // 根据status码解析错误原因
            val errorMessage = when (status) {
                BluetoothGatt.GATT_WRITE_NOT_PERMITTED -> "无写入权限（特征可能只读，或设备拒绝）"
                BluetoothGatt.GATT_INVALID_ATTRIBUTE_LENGTH -> "数据长度超过特征允许的最大值"
                BluetoothGatt.GATT_INSUFFICIENT_AUTHENTICATION -> "需要先配对认证才能写入"
                BluetoothGatt.GATT_INSUFFICIENT_ENCRYPTION -> "需要加密连接才能写入"
                BluetoothGatt.GATT_FAILURE -> "通用写入失败（可能是连接中断）"
                else -> "未知错误，状态码：$status"
            }
            mClientActionListener.log(TAG_GATT, "特征写入失败：$errorMessage")
        }
    }
}

3. 关键注意事项 #

• 确保你在调用device.connectGatt(context, autoConnect, gattCallback)时传入了上面的回调实例，否则拿不到任何结果。
• 如果writeCharacteristic返回false，大概率是GATT连接已经断开，或者设备处于不可用状态，这时候要先检查连接状态。

这样下来，不管是本地设置数据失败，还是远程写入失败，你都能拿到明确的错误原因啦！

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