蓝牙技术作为短距离无线通信的重要支柱,已深度融入物联网、可穿戴设备、智能家居、工业控制等场景。在Java生态中,Java蓝牙API(即JSR-82规范)为开发者提供了跨平台、标准化的蓝牙开发接口,支持经典蓝牙(BR/EDR)与低功耗蓝牙(BLE)的发现、连接、数据传输等核心功能。本页系统梳理Java蓝牙API的技术体系、实现机制、工程实践与常见问题,助您快速构建稳定可靠的蓝牙应用。
自2003年JSR-82正式发布以来,该规范定义了javax.bluetooth与javax.obex两个核心包,统一了蓝牙设备发现、服务注册、RFCOMM/SDP协议交互等底层操作。尽管Java ME时代已式微,但其设计思想仍深刻影响着现代蓝牙开发框架——Android SDK中的BluetoothAdapter、BluetoothSocket等组件,实质上是对JSR-82精神的延续与扩展。尤其在嵌入式Linux系统(如树莓派、BeagleBone)中,结合BlueZ协议栈与RXTX库,Java蓝牙API仍可作为轻量级服务端通信方案发挥关键作用。
值得注意的是,自Android 3.0起,Google逐步弱化对JSR-82的原生支持,转而推动基于BluetoothManager的原生API。但开源社区仍维护着多个兼容实现,如BlueCove(已停止更新)、libbluez-java等。本文将结合历史规范与现代实践,重点解析:
所有案例均经真实项目验证,覆盖串口透传、设备配对、状态监控、异常恢复等高频场景,适合从入门到进阶的开发者参考。
JSR-82规范基于Bluetooth Specification v1.1/v1.2制定,核心接口包括DiscoveryAgent、RemoteDevice、LocalDevice、ServiceRecord等,共同构成设备发现与服务查询的完整链路。以下为关键组件的深度解析:
设备发现分为两阶段:Inquiry(主动扫描附近设备)与Service Search(查询特定服务)。DiscoveryAgent通过startInquiry()触发 inquiry,触发DeviceDiscoveryListener回调,返回RemoteDevice对象。该对象包含蓝牙地址(getBluetoothAddress())与友好名称(getFriendlyName()),支持通过isTrustedDevice()判断是否为可信设备。
DiscoveryAgent agent = LocalDevice.getLocalDevice().getDiscoveryAgent(); agent.startInquiry(DiscoveryAgent.GIAC, listener); // GIAC为通用不可发现访问码,覆盖全部设备类型
需注意:设备发现为异步操作,可能耗时数秒,建议配合ProgressBar或Loading提示。在Android 6.0+中,还需动态申请ACCESS_FINE_LOCATION权限,因蓝牙扫描本质属于位置推断手段。
通过UUID确定服务类型(如SerialPortProfile=0x1101),使用ServiceSearch完成服务发现。ServiceRecord提供getURLs()获取连接URL,getAttributes()获取服务属性(如服务名称、协议参数)。典型代码如下:
UUID[] searchSet = {new UUID(0x1101)}; // SPP服务 agent.searchServices(null, searchSet, remoteDevice, listener);
服务发现结果通过ServiceSearchListener返回,ServiceRecord的getAttributeValue(0x0100)对应服务名称,0x0003为协议描述列表(包含RFCOMM通道号)。
使用Connector.open()打开连接,URL格式为bt://[设备地址][:通道号]。通道号需从ServiceRecord中提取(RFCOMM通道号位于ProtocolDescriptorList属性内)。连接建立后,通过getInputStream()/getOutputStream()进行双向数据传输。
String url = "bt://" + device.getBluetoothAddress() + ":1"; StreamConnection conn = (StreamConnection)Connector.open(url); InputStream is = conn.openInputStream(); OutputStream os = conn.openOutputStream();
关键点:通道号必须与服务端监听端口一致;连接过程可能抛出IOException,需处理连接超时(如设置Connector.OPEN_TIMEOUT=5000ms);建议使用BufferedInputStream包装提升吞吐效率。
本地设备可通过LocalDevice.getRecord()注册服务,并使用Connector.open("btspp://localhost:..." + uuid)开启监听。服务端监听URL格式为btspp://localhost:[UUID],返回StreamConnectionNotifier对象,调用acceptAndOpen()阻塞等待客户端连接。
String uuid = "00001101-0000-1000-8000-00805F9B34FB"; String url = "btspp://localhost:" + uuid + ";name=JavaBluetoothServer"; StreamConnectionNotifier notifier = (StreamConnectionNotifier)Connector.open(url); StreamConnection conn = notifier.acceptAndOpen();
服务注册需设置ServiceRecord的AttributeID,例如:
ServiceRecord record = LocalDevice.getLocalDevice().getRecord(null); record.setAttributeValue(0x0100, new StringAttribute("MySerialService")); record.setAttributeValue(0x0001, new ServiceRecord(new UUID(0x1101, true)));
自Bluetooth 4.0起,BLE成为主流。虽然JSR-82未原生支持BLE,但其GATT架构可通过Android BLE API或BlueZ D-Bus接口实现。核心概念包括:
在Android中,通过BluetoothGattCallback监听连接状态与服务发现结果:
BluetoothManager manager = (BluetoothManager) getSystemService(BLUETOOTH_SERVICE); BluetoothAdapter adapter = manager.getAdapter(); BluetoothDevice device = adapter.getRemoteDevice("AA:BB:CC:DD:EE:FF"); BluetoothGatt gatt = device.connectGatt(this, false, callback);
连接后调用gatt.discoverServices(),回调onServicesDiscovered()中获取BluetoothGattService列表,遍历其BluetoothGattCharacteristic对象即可读取/写入/订阅数据。
写入操作需注意权限设置:
characteristic.setWriteType(BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT); characteristic.setValue(new byte[]{0x01, 0x02}); gatt.writeCharacteristic(characteristic);
读取操作需等待onCharacteristicRead回调:
gatt.readCharacteristic(characteristic); // 在onCharacteristicRead中处理result.getValue()
订阅通知需配置Descriptor:
descriptor = characteristic.getDescriptor(UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")); descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE); gatt.writeDescriptor(descriptor);
数据接收通过onCharacteristicChanged()回调,注意处理字节序(如小端序需转换)。
| 平台 | 支持方式 | 关键类库 | 限制 |
|---|---|---|---|
| Android | 原生API | BluetoothGatt, BluetoothLeScanner | Android 4.3+;需定位权限 |
| iOS | CoreBluetooth | CBCentralManager, CBPeripheral | iOS 5+;需Info.plist声明权限 |
| Linux | BlueZ + D-Bus | libdbus-1-dev, bluez-tools | 需root权限;内核≥3.3 |
| Java桌面 | BlueCove + libbluez | javax.bluetooth | BlueCove已停止维护;Linux仅支持经典蓝牙 |
Android从API 1起支持蓝牙,但API 18(Android 4.3)引入BLE API后才实现全面支持。当前主流方案为:
AndroidManifest.xml需声明:
<uses-permission android:name="android.permission.BLUETOOTH" /> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
运行时权限申请示例:
if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) { ActivityCompat.requestPermissions(this, new String[]{ Manifest.permission.ACCESS_FINE_LOCATION }, REQUEST_FINE_LOCATION); }
设备适配注意:部分设备(如华为P30)禁用经典蓝牙串口服务,需优先使用BLE方案。
通过反射获取BluetoothDevice的createRfcommSocket方法(部分设备未公开):
Method method = device.getClass().getMethod("createRfcommSocket", int.class); BluetoothSocket socket = (BluetoothSocket) method.invoke(device, 1);
更可靠的方式是使用Android的BluetoothSocket.connect()直接连接SPP服务:
UUID SPP_UUID = UUID.fromString("00001101-0000-1000-8000-00805F9B34FB"); BluetoothSocket socket = device.createRfcommSocketToServiceRecord(SPP_UUID); socket.connect();
⚠️ 警告:部分设备需先取消配对再重连,否则connect()可能返回SocketException。
为提升吞吐量,可动态协商MTU:
gatt.requestMtu(517); // 回调onMtuChanged中使用新MTU发送分片数据
分片发送示例(每包512字节):
byte[] data = "large_data...".getBytes(); for (int i = 0; i < data.length; i += 512) { int length = Math.min(512, data.length - i); characteristic.setValue(Arrays.copyOfRange(data, i, i + length)); gatt.writeCharacteristic(characteristic); }
BlueZ是Linux官方蓝牙协议栈,自内核2.6.17起集成。在Java中可通过D-Bus接口(org.bluez)操作蓝牙设备,需依赖libdbus-java库。
通过D-Bus调用Adapter1接口的StartDiscovery()开始扫描:
DBusConnection conn = DBusConnection.getConnection(DBusConnection.SYSTEM); Adapter1 adapter = conn.getPeer("org.bluez", "/org/bluez/hci0", Adapter1.class); adapter.StartDiscovery();
扫描结果通过Device1接口的PropertiesChanged信号获取,设备地址格式为/dev/org/bluez/hci0/dev_XX_XX_XX_XX_XX_XX。
配对需调用Device1.Pair(),触发Agent回调(如PasskeyRequested)。在Java中实现org.bluez.Agent1接口:
public class MyAgent implements Agent1 { @Override public void RequestPasskey(String device) throws DBusException { // 返回6位数字(如123456) return 123456L; } }
注册Agent:
conn.exportObject("/org/bluez/agent", new MyAgent()); adapter.RegisterAgent(new ObjectPath("/org/bluez/agent"), "DisplayOnly");
通过D-Bus的SerialPort1接口创建RFCOMM通道:
SerialPort1 port = conn.getPeer("org.bluez", "/org/bluez/hci0", SerialPort1.class); String path = port.CreateSerialPort("/org/bluez/hci0", "1101", true);
返回路径如/dev/rfcomm0,Java中可通过RXTX库访问串口设备:
SerialPort port = (SerialPort) new CommPortIdentifier() .getPortIdentifier("/dev/rfcomm0").open("JavaBlue", 1000);
可能原因:
解决方案:
优化策略:
启动命令:
sudo systemctl start bluetooth sudo systemctl enable bluetooth
检查服务状态:
systemctl status bluetooth bluetoothctl --list
| 设备类型 | 推荐型号 | 关键特性 |
|---|---|---|
| 开发板 | Raspberry Pi 4 | 支持BlueZ 5.50+;双模蓝牙5.0 |
| Android手机 | Pixel 6 | Android 13原生支持BLE 5.3 |
| BLE模块 | CC2640R2F | TI官方SDK;低功耗典型值1.7μA |
| 串口透传 | HC-05 | 经典蓝牙SPP;AT指令配置 |
场景:工厂设备通过蓝牙串口上传温度、振动数据至Android平板
实现方案:
关键代码:
byte[] buffer = new byte[128]; int bytes = is.read(buffer); float temperature = ByteBuffer.wrap(buffer, 0, 4).order(ByteOrder.LITTLE_ENDIAN).getFloat(); double vibration = ByteBuffer.wrap(buffer, 4, 8).order(ByteOrder.LITTLE_ENDIAN).getDouble();
场景:手环通过GATT服务同步步数、心率数据至手机
服务结构:
心率特征值(0x2A37)格式:第一个字节为 flags(Bit0=1表示心率值为8位整数),后续为心率值。
场景:树莓派作为蓝牙-云平台中转站,接收BLE设备数据并推送至MQTT
实现流程:
A:Android 12引入新的蓝牙权限模型(BLUETOOTH_SCAN/BLUETOOTH_CONNECT),但API本质兼容。建议使用BluetoothLeScanner替代已废弃的startLeScan()。
A:Android最多支持7个经典蓝牙连接(RFCOMM限制),BLE可支持20+设备。建议采用主从架构,由中心设备(如平板)统一管理子设备连接池。
A:经典蓝牙理论速率1Mbps(实际约200KB/s),BLE 4.0为250KB/s,BLE 5.0可达2MB/s。瓶颈主要来自:① 串口协议开销 ② Android系统调度延迟 ③ 设备射频性能。优化方向:增大MTU、合并小包、使用NIO非阻塞IO。