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

SerialPort-4.0.+

项目官网

Java版本使用说明

介绍

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实例

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

设置UUID

• 传统设备

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

• BLE设备

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

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

搜索设备

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

停止搜索

serialPort.cancelDiscovery(this)

搜索状态监听

//status 为搜索状态
serialPort.setDiscoveryStatusCallback{ status ->  

}

//搜索状态带类型的监听

//deviceType = SerialPort.DISCOVERY_BLE 搜索BLE设备

//deviceType = SerialPort.DISCOVERY_LEGACY 搜索传统类型

//status 为搜索状态

serialPort.setDiscoveryStatusWithTypeCallback { deviceType, status ->



}

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

获取搜索结果

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

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

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

连接设备

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

serialPort.openDiscoveryActivity()

• 打开自定义的搜索页面

val intent = Intent(this,YourActivity::class.java)
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 ->


}

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

serialPort.setConnectionStatusCallback { status, bluetoothDevice ->


}

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

设置接收数据格式

//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.sendData("hello")

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

接收消息监听

serialPort.setReceivedDataCallback { string ->


}

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

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

val string = serialPort.hexStringToString(hexString)

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

修改Toast提示

//是否显示
SerialPortToast.connectSucceeded.status = true
//提示内容
SerialPortToast.connectSucceeded.content = "连接成功"
//显示时长 Toast.LENGTH_SHORT 或 Toast.LENGTH_LONG
SerialPortToast.connectSucceeded.time = Toast.LENGTH_SHORT

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