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) -> {
			<span class="token keyword">return</span> <span class="token keyword">null</span><span class="token punctuation">;</span>
       	<span class="token punctuation">}</span><span class="token punctuation">)</span>
       	<span class="token comment">//搜索状态带类型的监听</span>
        <span class="token comment">//deviceType = SerialPort.DISCOVERY_BLE 搜索BLE设备</span>
        <span class="token comment">//deviceType = SerialPort.DISCOVERY_LEGACY 搜索传统类型</span>
        <span class="token comment">//status 为搜索状态</span>
        <span class="token punctuation">.</span><span class="token function">setDiscoveryStatusWithTypeCallback</span><span class="token punctuation">(</span><span class="token punctuation">(</span>deviceType<span class="token punctuation">,</span> status<span class="token punctuation">)</span> <span class="token operator">-&gt;</span> <span class="token punctuation">{<!-- --></span>

			<span class="token keyword">return</span> <span class="token keyword">null</span><span class="token punctuation">;</span>
		<span class="token punctuation">}</span><span class="token punctuation">)</span>
		<span class="token comment">//连接状态监听(status 为连接状态,bluetoothDevice 为连接设备)</span>
        <span class="token punctuation">.</span><span class="token function">setConnectionStatusCallback</span><span class="token punctuation">(</span><span class="token punctuation">(</span>status<span class="token punctuation">,</span>bluetoothDevice<span class="token punctuation">)</span> <span class="token operator">-&gt;</span><span class="token punctuation">{<!-- --></span>

            <span class="token keyword">return</span> <span class="token keyword">null</span><span class="token punctuation">;</span>
        <span class="token punctuation">}</span><span class="token punctuation">)</span>
        <span class="token comment">//接收数据监听(string 为收到的数据)</span>
        <span class="token punctuation">.</span><span class="token function">setReceivedDataListener</span><span class="token punctuation">(</span><span class="token punctuation">(</span>string<span class="token punctuation">)</span> <span class="token operator">-&gt;</span> <span class="token punctuation">{<!-- --></span>

            <span class="token keyword">return</span> <span class="token keyword">null</span><span class="token punctuation">;</span>
        <span class="token punctuation">}</span><span class="token punctuation">)</span>
        <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

设置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");

1. BLE设备连接

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

断开连接

serialPort.disconnect()

连接状态监听

serialPort.setConnectStatusCallback((status,device)->{
<span class="token keyword">return</span> <span class="token keyword">null</span><span class="token punctuation">;</span>


});

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

serialPort.setConnectionStatusCallback((status,bluetoothDevice)->{
<span class="token keyword">return</span> <span class="token keyword">null</span><span class="token punctuation">;</span>


});

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

设置接收数据格式

//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) -> {
<span class="token keyword">return</span> <span class="token keyword">null</span><span class="token punctuation">;</span>


});

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

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

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);

项目	描述	默认值
connectSucceeded	连接成功时	连接成功
connectFailed	连接失败时	连接失败
disconnect	断开连接时	断开连接
connectFirst	未连接设备时执行发送数据	请先连接设备
disconnectFirst	已连接设备后执行连接操作	请先断开连接
permission	询问是否开启定位权限	请先开启位置权限
hexTip	发送十六进制时，数据格式不对提示	请输入的十六进制数据保持两位，不足前面补0
openBluetoothSucceeded	打开蓝牙成功时	蓝牙打开成功
openBluetoothFailed	打开蓝牙失败时	蓝牙打开失败