SerialPort-4.0.+ 使用说明（Java版本）

SerialPort-4.0.+

项目官网

Kotlin版本使用说明

介绍

SerialPort 是一个开源的对 Android 蓝牙串口通信的轻量封装库，轻松解决了构建自己的串口调试APP的复杂程度，让人可以专注追求自己设计，不用考虑蓝牙串口底层的配置。
相较于3.0.+版本，4.0.+新增了对蓝牙4.0及以上设备的支持。具体更新内容见下文详细说明。

特性

• 兼容传统蓝牙与BLE蓝牙设备
• 内部集成搜索页面
• 自动重连上一次连接的设备
• 间隔时间自动重连
• Toast提示信息修改

QQ技术交流群

最新版本信息

• 4.1.0
  • 修复内置搜索页面搜索到设备名为空的设备造成闪退的问题
  • 修复连接设备成功后会报广播接收器没有被注册的问题
  • 优化搜索结果的处理
  • 内置搜索页面新增设备类型字段
  • 内置搜索页面设备图标跟设备类型相匹配
  • 新增附带搜索设备类型的搜索状态回调
  • 新增通过设置地址自动区分设备连接函数
  • 优化对蓝牙开关状态的处理
• 4.0.2
  • 添加搜索状态回调，setDiscoveryStatusCallback
  • 接收回调函数名修改，由 setReceivedDataListener 变更为 setReceivedDataCallback
• 4.0.1
  • 修复 setLegacyUUID 和 setBleUUID 不能链式调用的问题
• 4.0.0
  • 新特性
    • 支持蓝牙4.0以上设备
    • 新增间隔自动重连
    • 新增Toast提示内容修改
    • 新增搜索页面忽视没有名字的设备
    • 部分API过时，详情见下文
  • 修复
    • 打开内置搜索页面闪退
    • 断开连接延时过长
    • 未连接时发送数据自动打开内置搜索页面不稳定
    • 发送十六进制 0A 时，自动变为 0A 0D

源码地址

• ​GitHub仓库
• Gitee仓库

Demo示例源码地址

网盘下载
站内下载

使用说明

添加依赖

• 根目录下的 build.gradle加入以下代码：

allprojects {repositories {//...maven { url 'https://jitpack.io' }}
}

• app模块的 build.gradle 加入以下代码即可：

dependencies {//根据自身网络情况以下两个仓库二选一即可implementation 'com.github.Shanyaliux:SerialPortSample:4.1.0' //国外仓库implementation 'com.gitee.Shanya:SerialPortSample:4.1.0' //国内仓库
}

获取SerialPort实例

SerialPort serialPort = SerialPortBuilder.INSTANCE//是否打印调试信息.isDebug(true)//设置传统设备连接UUID（不设置则为以下默认值）
//            .setLegacyUUID("00001101-0000-1000-8000-00805F9B34FB")//设置BLE设备连接UUID（不设置则为以下默认值）
//            .setBleUUID("0000ffe1-0000-1000-8000-00805f9b34fb")//是否开启启动时自动重连.autoConnect(false)//是否开启间隔时间自动重连（间隔时间time不设置则默认为10000ms）.setAutoReconnectAtIntervals(false, 10000)//搜索结果是否忽略没有名字的设备.isIgnoreNoNameDevice(true)//发送数据时若未连接设备是否自动打开内置搜索页面.autoOpenDiscoveryActivity(true)//在接收数据格式为十六进制时，是否将其自动转换为字符串.autoHexStringToString(false)//设置接收数据格式（若不设置则默认为字符串）
//            .setReadDataType(SerialPort.READ_STRING)//设置发送数据格式（若不设置则默认为字符串）
//            .setSendDataType(SerialPort.SEND_STRING)//搜索状态监听(status 为搜索状态).setDiscoveryStatusCallback((status) -> {return null;})//搜索状态带类型的监听//deviceType = SerialPort.DISCOVERY_BLE 搜索BLE设备//deviceType = SerialPort.DISCOVERY_LEGACY 搜索传统类型//status 为搜索状态.setDiscoveryStatusWithTypeCallback((deviceType, status) -> {return null;})//连接状态监听(status 为连接状态,bluetoothDevice 为连接设备).setConnectionStatusCallback((status,bluetoothDevice) ->{return null;})//接收数据监听(string 为收到的数据).setReceivedDataListener((string) -> {return null;}).build(this);

设置UUID

• 传统设备

SerialPort.Companion.setLegacyUUID("00001101-0000-1000-8000-00805F9B34FB");

• BLE设备

SerialPort.Companion.setBleUUID("0000ffe1-0000-1000-8000-00805f9b34fb");

BLE设备的UUID可以在连接后调用 serialPort.printPossibleBleUUID() 来查看一些可选值

搜索设备

//以下两种方案均可
serialPort.doDiscovery(this);
SerialPortBuilder.INSTANCE.doDiscovery(this);

停止搜索

serialPort.cancelDiscovery(this);

搜索状态监听

//status 为搜索状态
serialPort.setDiscoveryStatusCallback((status) ->{  return null;
});
//搜索状态带类型的监听
//deviceType = SerialPort.DISCOVERY_BLE 搜索BLE设备
//deviceType = SerialPort.DISCOVERY_LEGACY 搜索传统类型
//status 为搜索状态
serialPort.setDiscoveryStatusWithTypeCallback((deviceType, status) -> {return null;
});

若多处设置了监听，仅最后一次设置的生效

获取搜索结果

serialPort.getPairedDevicesList(); //获取已配对设备
serialPort.getUnPairedDevicesList(); //获取未配对设备

上述方法在4.0.0开始被弃用，建议使用以下方法

serialPort.getPairedDevicesListBD(); //获取已配对设备
serialPort.getUnPairedDevicesListBD(); //获取未配对设备

连接设备

• 打开内部集成的搜索页面

serialPort.openDiscoveryActivity();

• 打开自定义的搜索页面

Intent intent = new Intent(this, YourActivity.class);
serialPort.openDiscoveryActivity(intent);

• 通过设备地址连接

1. 传统设备连接

serialPort.connectLegacyDevice("98:D3:32:21:67:D0");

2. BLE设备连接

serialPort.connectBle("98:D3:32:21:67:D0");

断开连接

serialPort.disconnect()

连接状态监听

serialPort.setConnectStatusCallback((status,device)->{return null;
});

上述方法在4.0.0开始被弃用，建议使用以下方法

serialPort.setConnectionStatusCallback((status,bluetoothDevice)->{return null;
});

若多处设置了监听，仅最后一次设置的生效

设置接收数据格式

//SerialPort.READ_HEX 十六进制
//SerialPort.READ_STRING 字符串
//不设置则默认字符串形式
serialPort.setReadDataType(SerialPort.READ_HEX);

目前BLE设备暂不支持设置数据格式设置

设置发送数据格式

//SerialPort.SEND_HEX 十六进制
//SerialPort.SEND_STRING 字符串
//不设置则默认字符串形式
serialPort.setSendDataType(SerialPort.SEND_HEX);

目前BLE设备暂不支持设置数据格式设置

发送数据

//以下两种方案均可
serialPort.sendData("hello");
SerialPortBuilder.INSTANCE.sendData("hello");

若发送的数据为十六进制，则输入的数据需要为偶数个，只有一位的需要在其前面补0，且字母大写
例如：发送0x0a 0x0D，需要写成 serialPort.sendData("0A 0D")

接收消息监听

serialPort.setReceivedDataCallback((string) -> {return null;
});

若多处设置了监听，仅最后一次设置的生效

十六进制字符串转换成字符串

String string = serialPort.hexStringToString(hexString);

此时的接收数据格式为十六进制

修改Toast提示

//是否显示
SerialPortToast.INSTANCE.getConnectSucceeded().setStatus(true);
//提示内容
SerialPortToast.INSTANCE.getConnectSucceeded().setContent("连接成功");
//显示时长 Toast.LENGTH_SHORT 或 Toast.LENGTH_LONG
SerialPortToast.INSTANCE.getConnectSucceeded().setTime(Toast.LENGTH_SHORT);