QSL4A 蓝牙与 NFC——Python 控制近距离通信

蓝牙 API

功能概览

QSL4A 的蓝牙 API 覆盖了 Android 蓝牙的核心功能：

• 扫描周围蓝牙设备
• 查看已配对设备列表
• 与蓝牙设备建立连接（作为客户端）
• 向已连接设备发送和接收数据
• 开启蓝牙可发现模式（让其他设备搜到自己）

蓝牙扫描

扫描周围的蓝牙设备：

from androidhelper import Android
droid = Android()

# 启动扫描
droid.bluetoothStartDiscovery()
import time
time.sleep(10)  # 扫描 10 秒

# 获取扫描到的设备列表
devices = droid.bluetoothGetDiscoveredDevices().result
for device in devices:
    print(f"名称: {device.get('name')}, 地址: {device.get('address')}")

# 停止扫描
droid.bluetoothCancelDiscovery()

查看已配对设备

paired = droid.bluetoothGetBondedDevices().result
for device in paired:
    print(f"已配对: {device.get('name')} ({device.get('address')})")

连接和通信

和蓝牙设备（如串口蓝牙模块）建立连接后，可以发送和接收数据：

# 连接到指定地址的设备（需要先配对）
success = droid.bluetoothConnect("AA:BB:CC:DD:EE:FF").result

if success:
    # 发送数据
    droid.bluetoothWrite("AT\r\n")
    
    # 接收响应
    response = droid.bluetoothRead()
    print(response)
    
    # 断开连接
    droid.bluetoothDisconnect()

权限需求

Android 12（API 31）之后，蓝牙权限被拆得更细。如果蓝牙扫描返回空列表，99% 是位置权限没给——Android 要求扫描蓝牙时必须同时能获取位置。

NFC API

NFC 是什么

NFC（Near Field Communication，近场通信）是一种短距离无线通信技术，常见于：

• 刷门禁卡
• 手机支付
• NFC 标签（信息写入或读取）
• 快速配对蓝牙设备

QSL4A NFC 功能

QSL4A 的 NFC API 主要支持读取 NFC 标签：

# 开启 NFC 监听
droid.nfcEnableForegroundDispatch()

# 等待读取标签
import time
time.sleep(60)  # 在这 60 秒内把 NFC 标签靠近手机

# 获取读到的标签数据
tag = droid.nfcGetTagID().result
print(f"标签 ID: {tag}")

# 关闭监听
droid.nfcDisableForegroundDispatch()

NFC 权限

需要 NFC 权限（android.permission.NFC）。部分手机不支持 NFC，相关 API 会静默失败。

实际应用场景

蓝牙场景

• IoT 设备控制：蓝牙继电器、智能插座、传感器模块，通过蓝牙 AT 指令控制
• 蓝牙键盘 / 键鼠：某些 QSL4A 版本支持监听蓝牙设备输入
• 多设备协同：两台装了 QPython 的手机通过蓝牙传数据

NFC 场景

• 读取 NFC 标签：把标签上的 URL、文本、联系方式读到 Python 脚本里处理
• 门禁卡模拟：高级玩法，需要手机支持 HCE（Host Card Emulation）

开发注意事项

蓝牙连接超时

某些蓝牙设备连接需要几秒甚至几十秒。建议在连接代码里加超时处理：

import time
start = time.time()
while time.time() - start < 15:  # 15 秒超时
    result = droid.bluetoothConnect(address).result
    if result:
        break
    time.sleep(1)
else:
    print("连接超时")

蓝牙和位置权限

Android 12+ 扫描蓝牙需要同时授予位置权限。如果蓝牙扫描返回空列表，先检查位置权限。

后台蓝牙操作

Android 对后台蓝牙操作限制很严。如果脚本要持续监听蓝牙，需要申请前台服务权限（FOREGROUND_SERVICE）并显示通知。

小结

蓝牙和 NFC 把 QPython 的硬件控制能力从「自带传感器」扩展到「外部设备通信」。蓝牙扫描 + 连接 + 收发数据这一套 API 在 IoT 场景下特别实用。NFC 主要用于标签读取。注意 Android 12+ 蓝牙扫描必须配合位置权限，这是最常踩的坑。

继续看 系统服务接口 了解 QSL4A 的系统级 API。