使用Pyjnius调用Android BLE的connectGatt方法报参数不匹配错误如何解决

核心问题根因 #

该报错90%以上的场景不是参数类型写得不对，而是两个隐式问题：

• Pyjnius无法将Python实现的接口类自动识别为BluetoothGattCallback子类实例
• 不同安卓API等级下connectGatt的重载签名存在差异，没有对应适配

可行解决步骤 #

1. 修正Java回调类实现与打包配置 #

• 在项目根目录新建src文件夹，按照你Java类的包名创建对应层级路径，比如类包名为com.yourproject.ble，就创建src/com/yourproject/ble/BluetoothGattImplem.java
• 在buildozer.spec中添加源码目录配置，确保Java类被打包进APK：

android.add_src = src/

• 编写标准无参构造的Java回调类，不要加自定义构造方法，所有重写方法加@Override注解：

package com.yourproject.ble;

import android.bluetooth.BluetoothGatt;
import android.bluetooth.BluetoothGattCallback;

public class BluetoothGattImplem extends BluetoothGattCallback {
    @Override
    public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {
        super.onConnectionStateChange(gatt, status, newState);
    }

    // 其余需要的回调方法如onServicesDiscovered等按照上述格式添加即可
}

2. 修正Python侧调用逻辑 #

不要用Python类实现Java接口当参数传入，直接实例化你写的Java回调类，再绑定Python处理函数即可：

from jnius import autoclass

# 导入所需原生类
BluetoothDevice = autoclass('android.bluetooth.BluetoothDevice')
Build = autoclass('android.os.Build')
BluetoothGattImplem = autoclass('com.yourproject.ble.BluetoothGattImplem')
PythonActivity = autoclass('org.kivy.android.PythonActivity')

# 实例化Java侧回调对象
gatt_callback = BluetoothGattImplem()

# 绑定Python处理函数到回调方法
def on_conn_state_change(gatt, status, new_state):
    # 此处写你自己的状态处理逻辑
    pass
gatt_callback.onConnectionStateChange = on_conn_state_change

# 按API等级调用对应重载的connectGatt方法
current_activity = PythonActivity.mActivity
if Build.VERSION.SDK_INT >= 23:
    # API≥23重载签名：connectGatt(Context, autoConnect, callback, transport)
    # transport传2对应TRANSPORT_LE，指定使用BLE传输
    gatt = target_ble_device.connectGatt(current_activity, False, gatt_callback, 2)
else:
    # API<23重载签名：connectGatt(Context, autoConnect, callback)
    gatt = target_ble_device.connectGatt(current_activity, False, gatt_callback)

注意：第一个参数必须传当前Activity实例，不要传Application Context，高版本安卓下会触发参数匹配错误

3. 补全权限配置 #

在buildozer.spec中添加所有必要的蓝牙权限，安卓12+新增的权限必须配置：

android.permissions = BLUETOOTH, BLUETOOTH_ADMIN, ACCESS_FINE_LOCATION, BLUETOOTH_CONNECT, BLUETOOTH_SCAN
android.api = 33

同时在Python代码中运行时申请上述敏感权限，权限未获批的情况下调用蓝牙方法也会抛出无明确提示的参数异常。

内容的提问来源于stack exchange，提问作者Cinematic Galaxy Ita