Welcome to SerialPort’s documentation!¶

安装¶

编辑Build.gradle文件并添加以下依赖项。

dependencies {
    implementation 'cn.shanyaliux.serialport:serialport:4.2.0'
}

如果你需要使用4.1.6及其以下版本，则按如下操作：

添加 JitPack 仓库将 JitPack 存储库添加到您的构建文件中

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

添加依赖

dependencies {
    implementation 'com.gitee.Shanya:SerialPortSample:4.1.6'        //国内仓库
    implementation 'com.github.Shanyaliux:SerialPortSample:4.1.6'   //国外仓库
}

快速上手 (Kotlin)¶

构建SerialPort实例¶

val serialPort = SerialPortBuilder.build(this)

搜索设备¶

使用方法 doDiscovery(context) 搜索设备：

serialPort.doDiscovery(this)

使用方法 getPairedDevicesListBD() 和 getUnPairedDevicesListBD() 获取搜索结果：

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

连接设备¶

想要成功的连接设备，并且完成通信，设置正确的UUID是必不可少的一步。

设置传统设备UUID¶

使用 SerialPort 的静态方法 setLegacyUUID(uuid) 设置传统设备的UUID：

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

传统设备一般情况下，可以不用设置UUID，使用默认的即可。

设置BLE设备UUID¶

使用 SerialPort 的静态方法 setBleUUID(uuid) 设置BLE设备的UUID：

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

BLE设备大多数情况下都需要设置UUID，具体的UUID可以查询手册或咨询卖家。

除此之外，也可以使用方法 printPossibleBleUUID() 打印出可行的UUID，自行选择尝试：

serialPort.printPossibleBleUUID()

建立连接¶

使用方法 openDiscoveryActivity() 打开内置的搜索页面选择设备进行连接：

serialPort.openDiscoveryActivity()

不想使用内置的搜索页面怎么办？

可以设置自定义的搜索页面或者直接使用设备地址进行连接。详见使用自定义的界面

接收消息¶

使用方法 setReceivedDataCallback(receivedDataCallback) 设置一个接收消息监听器：

serialPort.setReceivedDataCallback { data ->

        }

除此之外，你还可以在构建实例时配置监听器：

val serialPort = SerialPortBuilder
            .setReceivedDataCallback { data ->

            }
            .build(this)

发送消息¶

使用方法 sendData(data) 发送消息：

serialPort.sendData("Hello World")

至此，你已经可以快速的开发一款能够完成基本收发数据的串口应用了。当然，SerialPort 还有着更多的功能，请继续阅读说明文档。

快速上手 (Java)¶

构建SerialPort实例¶

SerialPort serialPort = SerialPortBuilder.INSTANCE.build(this);

搜索设备¶

使用方法 doDiscovery(context) 搜索设备：

serialPort.doDiscovery(this);

使用方法 getPairedDevicesListBD() 和 getUnPairedDevicesListBD() 获取搜索结果：

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

如果搜索未结束，则可能获取的未配对设备列表为空或者不全.

连接设备¶

想要成功的连接设备，并且完成通信，设置正确的UUID是必不可少的一步。

设置传统设备UUID¶

使用 SerialPort 的静态方法 setLegacyUUID(uuid) 设置传统设备的UUID：

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

传统设备一般情况下，可以不用设置UUID，使用默认的即可。

设置BLE设备UUID¶

使用 SerialPort 的静态方法 setLegacyUUID(uuid) 设置BLE设备的UUID：

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

BLE设备大多数情况下都需要设置UUID，具体的UUID可以查询手册或咨询卖家。

除此之外，也可以使用方法 printPossibleBleUUID() 打印出可行的UUID，自行选择尝试：

serialPort.printPossibleBleUUID()

建立连接¶

使用方法 openDiscoveryActivity() 打开内置的搜索页面选择设备进行连接：

serialPort.openDiscoveryActivity();

不想使用内置的搜索页面怎么办？

可以设置自定义的搜索页面或者直接使用设备地址进行连接。详见使用自定义的界面

接收消息¶

使用方法 setReceivedDataCallback(receivedDataCallback) 设置一个接收消息监听器：

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

除此之外，你还可以在构建实例时配置监听器：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .setReceivedDataCallback( (data) -> {

                    return null;
                })
                .build(this);

发送消息¶

使用方法 sendData(data) 发送消息：

serialPort.sendData("Hello World");

至此，你已经可以快速的开发一款能够完成基本收发数据的串口应用了。当然，SerialPort 还有着更多的功能，请继续阅读说明文档。

服务端¶

现在，可以构建Android服务端，实现两台Android之间的蓝牙通信。(目前仅支持单设备连接)

构建实例¶

val serialPortServer = SerialPortServerBuilder
            .setServerName("SerialPortServer")
            .setServerUUID("00001101-0000-1000-8000-00805F9B34FB")
            .setServerReceivedDataCallback {
                
            }
            .setServerConnectStatusCallback { status, bluetoothDevice ->
                
            }
            .build(this)

setServerName 设置服务端名称
setServerUUID 设置服务端UUID，客户端连接时需设置传统设备的UUID与此相同
setServerReceivedDataCallback 服务端接收消息监听
setServerConnectStatusCallback 服务端连接状态监听
- status 连接状态
- bluetoothDevice 连接设备，当status为false则其为null

打开服务¶

只有打开服务后，客户端才可以连接到服务端。

serialPortServer.openServer()

关闭服务¶

serialPortServer.closeServer()

设置服务端可发现状态¶

默认打开服务则会自动设置为可发现，关闭服务则设置为不可见。

setServerDiscoverable(status)

status 为 Boolean类型，表示可发现状态

断开连接¶

主动断开与客户端的连接

serialPortServer.disconnect()

发送消息¶

serialPortServer.sendData("Hello")

配置¶

调试模式¶

在调试程序的时候，我们可以打开调试模式，这样就会打印各式各样的日志信息，在正式发布APP时关掉此开关即可减少资源的开销。设置方式如下：

val serialPort = SerialPortBuilder
            .isDebug(true)
            .build(this)

自动重连¶

启动时重连¶

开启此功能后，会在构建实例的时候执行一次自动重连，重连对象为上一次成功连接的设备。设置方式如下：

val serialPort = SerialPortBuilder
            .autoConnect(true)
            .build(this)

间隔自动重连¶

开启此功能后，会间隔一段时间自动重连一次（时间可自行设置），重连对象为上一次成功连接的设备。设置方式如下：

val serialPort = SerialPortBuilder
			//第二个参数为间隔时间，若不指定则为默认 10000Ms
            .setAutoReconnectAtIntervals(true, 10000)
            .build(this)

忽略无名设备¶

开启此功能后，搜索设备时就会自动忽略设备名为空的设备。设置方式如下：

val serialPort = SerialPortBuilder
            .isIgnoreNoNameDevice(true)
            .build(this)

部分蓝牙设备可能会在第一次连接出现设备名为空的情况，请视情况而定开启此功能。

自动打开搜索界面¶

开启此功能后，在发送数据时，若发现未连接设备则会自动打开内置的搜索页面。设置方式如下：

val serialPort = SerialPortBuilder
            .autoOpenDiscoveryActivity(true)
            .build(this)

十六进制数据自动转换¶

开启此功能后，在收到的数据为十六进制时，会自动将其转换为字符串。设置方式如下：

val serialPort = SerialPortBuilder
            .autoHexStringToString(true)
            .build(this)

当然，你也可以使用方法 hexStringToString(hexString) 手动进行转换：

string = serialPort.hexStringToString(hexString)

内置搜索页面选择连接方式¶

开启此功能后在内置页面点击设备进行连接的时候，可以手动选择连接方式。但请注意若你的设备不支持你所选的连接方式，则连接不会成功。

val serialPort = SerialPortBuilder
            .setOpenConnectionTypeDialogFlag(true)
            .build(this)

配置器¶

配置可以将上述的多种配置一次性传入SerialPortBuilder。

val config = SerialPortConfig()
val serialPort = SerialPortBuilder
            .setConfig(config)
            .build(this)

其中配置器可设置的参数如下表所示 (加粗的表示默认值)：

参数名称	值
debug	(bool) true / false
UUID_LEGACY	(string) 00001101-0000-1000-8000-00805F9B34FB
UUID_BLE	(string) 00001101-0000-1000-8000-00805F9B34FB
UUID_BLE_READ	(string) 无
UUID_BLE_SEND	(string) 无
autoConnect	(bool) true / false
autoReconnect	(bool) true / false
reconnectAtIntervals	(int) 10000
autoOpenDiscoveryActivity	(bool) true / false
autoHexStringToString	(bool) true / false
readDataType	SerialPort.READ_STRING / SerialPort.READ_HEX
sendDataType	SerialPort.SEND_STRING / SerialPort.SEND_HEX
ignoreNoNameDevice	(bool) true / false
openConnectionTypeDialogFlag	(bool) true / false

其中关于UUID的设置注意事项参考: ble设备设置UUID

设置搜索时长¶

使用此方法配置搜索设备时长：

//参数为时间，单位毫秒
val serialPort = SerialPortBuilder
            .setDiscoveryTime(10000)
            .build(this)

搜索和连接¶

内置的界面¶

为了更加方便快速的帮助开发串口通信应用程序，我们内部集成了一个必备的搜索和连接页面，使用方法 openDiscoveryActivity() 打开一个内置的界面：

serialPort.openDiscoveryActivity()

使用自定义的界面¶

当然了，在更多的情况我们的搜索和连接页面需要更加的美观和定制化。那么，可以使用方法 serialPort.openDiscoveryActivity(intent) 打开一个你自定义的页面：

//这里修改为你自定义的Activity即可
val intent = Intent(this,DiscoveryActivity::class.java)
serialPort.openDiscoveryActivity(intent)

搜索设备¶

开始搜索¶

使用方法 doDiscovery(context) 即可开始搜索设备：

serialPort.doDiscovery(this)

停止搜索¶

使用方法 cancelDiscovery(context) 即可开始搜索设备：

serialPort.cancelDiscovery(this)

搜索状态的监听¶

使用方法 setDiscoveryStatusWithTypeCallback(discoveryStatusWithTypeCallback) 或者 setDiscoveryStatusCallback(discoveryStatusCallback) 设置一个搜索状态监听器：

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

除此之外，你还可以在构建实例时配置监听器：

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

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

获取搜索结果¶

使用方法 getPairedDevicesListBD() 和 getUnPairedDevicesListBD() 获取搜索结果：

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

如果搜索未结束，则可能获取的未配对设备列表为空或者不全。

连接设备¶

想要成功的连接设备，并且完成通信，设置正确的UUID是必不可少的一步。

传统设备¶

设置UUID¶

使用 SerialPort 的静态方法 setLegacyUUID(uuid) 设置传统设备的UUID：

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

传统设备一般情况下，可以不用设置UUID，使用默认的即可。

建立连接¶

使用方法 connectLegacyDevice(address) 与传统设备建立连接：

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

BLE设备¶

设置UUID¶

使用 SerialPort 的静态方法 setBleUUID(uuid) 设置BLE设备的UUID，或者使用setBleSendUUID 和 setBleReadUUID 分别独立设置发送和接收的UUID：

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

如果独立设置了UUID，则以独立设置的为准。

BLE设备大多数情况下都需要设置UUID，具体的UUID可以查询手册或咨询卖家。

除此之外，也可以使用方法 printPossibleBleUUID() 打印出可行的UUID，详情见：打印uuid及其属性

建立连接¶

使用方法 connectBle(address) 与传统设备建立连接：

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

断开连接¶

使用方法 disconnect() 与传统设备建立连接：

serialPort.disconnect()

连接状态的监听¶

使用方法 setConnectionStatusCallback(connectionStatusCallback) 设置一个连接状态的监听器：

serialPort.setConnectStatusCallback { status, bluetoothDevice ->  
   
}

除此之外，你还可以在构建实例时配置监听器：

val serialPort = SerialPortBuilder
            .setConnectionStatusCallback { status, bluetoothDevice -> 
                
            }
            .build(this)

这里的 bluetoothDevice 使用的时官方的类，其包含了蓝牙的设备的各种信息。详见官方文档

在之前版本使用的是自定义的 Device 类（不建议使用），其包含了：设备名、设备地址、设备类型。其实现如下：

@Deprecated("该类在4.0.0版本被弃用,将直接使用官方的BluetoothDevice类代替")
data class Device(
    val name:String,
    val address:String,
    val type:Int = 0
)

BLE 可以工作回调¶

该回调在BLE设备连接成功，并且可以工作之后触发，可用于配置连接成功后自动发送消息。使用方法如下：

serialPort.setBleCanWorkCallback {

}

除此之外，你还可以在构建实例时配置监听器：

val serialPort = SerialPortBuilder
            .setBleCanWorkCallback {
   
			}
            .build(this)

收发数据¶

设置数据格式¶

使用方法 setReadDataType(type) 和 setSendDataType(type) 来设置手法数据的格式：

设置接收消息格式¶

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

除此之外，你还可以在构建实例时设置接收数据格式：

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

设置发送数据格式¶

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

除此之外，你还可以在构建实例时设置接收数据格式：

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

目前针对于BLE设备的数据收发暂不支持设置格式，仅支持字符串格式。如果实在需要十六进制的数据格式，暂时可以参考传统设备的处理方式自行实现。

参考代码链接：HexStringToString、StringToHex

接收消息¶

字符串和十六进制¶

使用方法 setReceivedDataCallback(receivedDataCallback) 设置一个接收消息监听器：

serialPort.setReceivedDataCallback { data ->

        }

除此之外，你还可以在构建实例时配置监听器：

val serialPort = SerialPortBuilder
            .setReceivedDataCallback { data ->

            }
            .build(this)

字节数组¶

在接收消息的时候，也可以选择获取字节数组，方法如下：

serialPort.setReceivedBytesCallback { bytes ->

        }

除此之外，你还可以在构建实例时配置监听器：

val serialPort = SerialPortBuilder
            .setReceivedBytesCallback { bytes ->

            }
            .build(this)

发送消息¶

使用方法 sendData(data) 发送消息：

字符串¶

serialPort.sendData("Hello World")

十六进制¶

serialPort.sendData("0C FF")

所有的十六进制应为两位，不足两位的前方补0，不区分大小写。

BLE设备发送字节数组¶

目前BLE设备支持直接发送字节数组

serialPort.sendData(bytes)

Toast提示设置¶

配置方法¶

//是否显示
SerialPortToast.connectSucceeded.status = true
//提示内容 content 是字符串id
SerialPortToast.connectSucceeded.content = R.string.connectSucceededToast
//显示时长 Toast.LENGTH_SHORT 或 Toast.LENGTH_LONG
SerialPortToast.connectSucceeded.time = Toast.LENGTH_SHORT

可选配置项¶

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

工具¶

打印UUID及其属性¶

若我们不能知晓当前BLE设备的UUID可以调用函数printPossibleBleUUID来打印出当前连接设备的可选UUID

其中Properties 为二进制数，其每一位对应的意思见下表：

数值（以十六进制表示）	意思
0x01	broadcastable
0x02	readable
0x04	can be written without response
0x08	can be written
0x10	supports notification
0x20	supports indication
0x40	supports write with signature
0x80	has extended properties

字符串转换成十六进制¶

/**
 * 字符串转换成十六进制
 * @param str 待转换的字符串
 * @return 十六进制数组
 */
DataUtil.string2hex("Hello")

字节数组按要求的编码格式转换成字符串¶

/**
 * 字节数组按要求的编码格式转换成字符串
 * @param bytes 带转换的字节数组
 * @param charsetName 要求的编码格式
 * @return 转换成功的字符串
 */
SerialPortTools.bytes2string(bytes, "GBK")

字符串按要求的编码格式转换成字节数组¶

/**
 * 字符串按要求的编码格式转换成字节数组
 * @param string 带转换的字符串
 * @param charsetName 要求的编码格式
 * @return 转换成功的字节数组
 */
SerialPortTools.bytes2string("Hello", "GBK")

配置¶

调试模式¶

在调试程序的时候，我们可以打开调试模式，这样就会打印各式各样的日志信息，在正式发布APP时关掉此开关即可减少资源的开销。设置方式如下：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .isDebug(true)
                .build(this);

自动重连¶

启动时重连¶

开启此功能后，会在构建实例的时候执行一次自动重连，重连对象为上一次成功连接的设备。设置方式如下：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .autoConnect(true)
                .build(this);

间隔自动重连¶

开启此功能后，会间隔一段时间自动重连一次（时间可自行设置），重连对象为上一次成功连接的设备。设置方式如下：

SerialPort serialPort = SerialPortBuilder.INSTANCE
    			//第二个参数为间隔时间，若不指定则为默认 10000Ms
                .setAutoReconnectAtIntervals(true, 10000)
                .build(this);

忽略无名设备¶

开启此功能后，搜索设备时就会自动忽略设备名为空的设备。设置方式如下：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .isIgnoreNoNameDevice(true)
                .build(this);

部分蓝牙设备可能会在第一次连接出现设备名为空的情况，请视情况而定开启此功能。

自动打开搜索界面¶

开启此功能后，在发送数据时，若发现未连接设备则会自动打开内置的搜索页面。设置方式如下：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .autoOpenDiscoveryActivity(true)
                .build(this);

十六进制数据自动转换¶

开启此功能后，在收到的数据为十六进制时，会自动将其转换为字符串。设置方式如下：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .autoHexStringToString(true)
                .build(this);

当然，你也可以使用方法 hexStringToString(hexString) 手动进行转换：

string = serialPort.hexStringToString(hexString)

内置搜索页面选择连接方式¶

开启此功能后在内置页面点击设备进行连接的时候，可以手动选择连接方式。但请注意若你的设备不支持你所选的连接方式，则连接不会成功。

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .setOpenConnectionTypeDialogFlag(true)
                .build(this);

配置器¶

配置可以将上述的多种配置一次性传入SerialPortBuilder。

SerialPortConfig config = new SerialPortConfig();
SerialPort serialPort = SerialPortBuilder.INSTANCE
                .setConfig(config)
                .build(this);

其中配置器可设置的参数如下表所示 (加粗的表示默认值)：

参数名称	值
debug	(bool) true / false
UUID_LEGACY	(string) 00001101-0000-1000-8000-00805F9B34FB
UUID_BLE	(string) 00001101-0000-1000-8000-00805F9B34FB
UUID_BLE_READ	(string) 无
UUID_BLE_SEND	(string) 无
autoConnect	(bool) true / false
autoReconnect	(bool) true / false
reconnectAtIntervals	(int) 10000
autoOpenDiscoveryActivity	(bool) true / false
autoHexStringToString	(bool) true / false
readDataType	SerialPort.READ_STRING / SerialPort.READ_HEX
sendDataType	SerialPort.SEND_STRING / SerialPort.SEND_HEX
ignoreNoNameDevice	(bool) true / false
openConnectionTypeDialogFlag	(bool) true / false

其中关于UUID的设置注意事项参考: ble设备设置UUID

设置搜索时长¶

使用此方法配置搜索设备时长：

//参数为时间，单位毫秒
SerialPort serialPort = SerialPortBuilder.INSTANCE
                .setDiscoveryTime(10000)
                .build(this);

搜索和连接¶

内置的界面¶

为了更加方便快速的帮助开发串口通信应用程序，我们内部集成了一个必备的搜索和连接页面，使用方法 openDiscoveryActivity() 打开一个内置的界面：

serialPort.openDiscoveryActivity();

使用自定义的界面¶

当然了，在更多的情况我们的搜索和连接页面需要更加的美观和定制化。那么，可以使用方法 serialPort.openDiscoveryActivity(intent) 打开一个你自定义的页面：

//这里修改为你自定义的Activity即可
Intent intent = new Intent(this, DiscoveryActivity.class);
serialPort.openDiscoveryActivity(intent);

搜索设备¶

开始搜索¶

使用方法 doDiscovery(context) 即可开始搜索设备：

serialPort.doDiscovery(this);

停止搜索¶

使用方法 cancelDiscovery(context) 即可开始搜索设备：

serialPort.cancelDiscovery(this);

搜索状态的监听¶

使用方法 setDiscoveryStatusWithTypeCallback(discoveryStatusWithTypeCallback) 或者 setDiscoveryStatusCallback(discoveryStatusCallback) 设置一个搜索状态监听器：

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

return null;
});

除此之外，你还可以在构建实例时配置监听器：

//status 为搜索状态
SerialPort serialPort = SerialPortBuilder.INSTANCE
                .setDiscoveryStatusCallback( (status) -> {

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

获取搜索结果¶

使用方法 getPairedDevicesListBD() 和 getUnPairedDevicesListBD() 获取搜索结果：

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

如果搜索未结束，则可能获取的未配对设备列表为空或者不全。

连接设备¶

想要成功的连接设备，并且完成通信，设置正确的UUID是必不可少的一步。

传统设备¶

设置UUID¶

使用 SerialPort 的静态方法 setLegacyUUID(uuid) 设置传统设备的UUID：

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

传统设备一般情况下，可以不用设置UUID，使用默认的即可。

建立连接¶

使用方法 connectLegacyDevice(address) 与传统设备建立连接：

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

BLE设备¶

设置UUID¶

使用 SerialPort 的静态方法 setBleUUID(uuid) 设置BLE设备的UUID，或者使用setBleSendUUID 和 setBleReadUUID 分别独立设置发送和接收的UUID：

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

如果独立设置了UUID，则以独立设置的为准。

BLE设备大多数情况下都需要设置UUID，具体的UUID可以查询手册或咨询卖家。

除此之外，也可以使用方法 printPossibleBleUUID() 打印出可行的UUID，详情见：打印uuid及其属性

建立连接¶

使用方法 connectBle(address) 与传统设备建立连接：

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

断开连接¶

使用方法 disconnect() 与传统设备建立连接：

serialPort.disconnect();

连接状态的监听¶

使用方法 setConnectionStatusCallback(connectionStatusCallback) 设置一个连接状态的监听器：

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

除此之外，你还可以在构建实例时配置监听器：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .setConnectionStatusCallback( (status, bluetoothDevice) -> {

                    return null;
                })
                .build(this);

这里的 bluetoothDevice 使用的时官方的类，其包含了蓝牙的设备的各种信息。详见官方文档

在之前版本使用的是自定义的 Device 类（不建议使用），其包含了：设备名、设备地址、设备类型。其实现如下：

@Deprecated("该类在4.0.0版本被弃用,将直接使用官方的BluetoothDevice类代替")
data class Device(
    val name:String,
    val address:String,
    val type:Int = 0
)

BLE 可以工作回调¶

该回调在BLE设备连接成功，并且可以工作之后触发，可用于配置连接成功后自动发送消息。使用方法如下：

serialPort.setBleCanWorkCallback( () -> {

        return null;
        });

除此之外，你还可以在构建实例时配置监听器：

SerialPort serialPort = SerialPortBuilder.INSTANCE
        .setBleCanWorkCallback( () -> {

        return null;
    })
    .build(this);

收发数据¶

设置数据格式¶

使用方法 setReadDataType(type) 和 setSendDataType(type) 来设置手法数据的格式：

设置接收消息格式¶

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

除此之外，你还可以在构建实例时设置接收数据格式：

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

设置发送数据格式¶

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

除此之外，你还可以在构建实例时设置接收数据格式：

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

目前针对于BLE设备的数据收发暂不支持设置格式，仅支持字符串格式。如果实在需要十六进制的数据格式，暂时可以参考传统设备的处理方式自行实现。

参考代码链接：HexStringToString、StringToHex

接收消息¶

字符串和十六进制¶

使用方法 setReceivedDataCallback(receivedDataCallback) 设置一个接收消息监听器：

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

除此之外，你还可以在构建实例时配置监听器：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .setReceivedDataCallback( (data) -> {

                    return null;
                })
                .build(this);

字节数组¶

在接收消息的时候，也可以选择获取字节数组，方法如下：

serialPort.setReceivedBytesCallback( (bytes) -> {
            
            return null;
        });

除此之外，你还可以在构建实例时配置监听器：

SerialPort serialPort = SerialPortBuilder.INSTANCE
                .setReceivedBytesCallback( (bytes) -> {

                    return null;
                })
                .build(this);

发送消息¶

使用方法 sendData(data) 发送消息：

字符串¶

serialPort.sendData("Hello World");

十六进制¶

serialPort.sendData("0C FF");

所有的十六进制应为两位，不足两位的前方补0，不区分大小写。

BLE设备发送字节数组¶

目前BLE设备支持直接发送字节数组

serialPort.sendData(bytes);

Toast提示设置¶

配置方法¶

//是否显示
SerialPortToast.INSTANCE.getConnectSucceeded().setStatus(true);
//提示内容 content 是字符串id
SerialPortToast.INSTANCE.getConnectSucceeded().setContent(R.string.connectSucceededToast);
//显示时长 Toast.LENGTH_SHORT 或 Toast.LENGTH_LONG
SerialPortToast.INSTANCE.getConnectSucceeded().setTime(Toast.LENGTH_SHORT);

可选配置项¶

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

工具¶

打印UUID及其属性¶

若我们不能知晓当前BLE设备的UUID可以调用函数printPossibleBleUUID来打印出当前连接设备的可选UUID

其中Properties 为二进制数，其每一位对应的意思见下表：

数值（以十六进制表示）	意思
0x01	broadcastable
0x02	readable
0x04	can be written without response
0x08	can be written
0x10	supports notification
0x20	supports indication
0x40	supports write with signature
0x80	has extended properties

字符串转换成十六进制¶

/**
 * 字符串转换成十六进制
 * @param str 待转换的字符串
 * @return 十六进制数组
 */
DataUtil.INSTANCE.string2hex("Hello");

字节数组按要求的编码格式转换成字符串¶

/**
 * 字节数组按要求的编码格式转换成字符串
 * @param bytes 带转换的字节数组
 * @param charsetName 要求的编码格式
 * @return 转换成功的字符串
 */
SerialPortTools.bytes2string(bytes, "GBK");

字符串按要求的编码格式转换成字节数组¶

/**
 * 字符串按要求的编码格式转换成字节数组
 * @param string 带转换的字符串
 * @param charsetName 要求的编码格式
 * @return 转换成功的字节数组
 */
SerialPortTools.bytes2string("Hello", "GBK");

有疑必看¶

功能支持¶

支持BLE设备吗？¶

支持，SerialPort 从 4.0.0 版本开始全面支持BLE设备。

有自动重连机制吗？¶

有，可以设置在启动时重连，也可以间隔时间自动重连。详见自动重连

常见问题¶

为什么自定义页面的可用设备列表为空？¶

在Android6.0之后一定要给上定位权限才可以搜索到可用设备。

为什么BLE设备连接成功了，不能收发消息，有时还是发出异常？¶

BLE设备连接成功后，还需要设置正确的UUID才可以正常通信。具体设置方法见设置BLE设备UUID

还有其他问题怎么解决？¶

开启调试模式¶

打开调试模式查看打印的日志信息。详见调试模式

利用强大的搜索引擎¶

_images/google.png

_images/baidu.png

加群¶

若通过以上方法仍未解决问题，请加入QQ技术交流群。

_images/qq.png

更新日志¶

4.2.0 版本已经在 7/6/2022 发布:¶

修复一些关于蓝牙权限的编译告警
升级Kotlin和Gradle版本
标记ConnectionResultCallback过时
新增Ble设备发送字节数组
新增Ble设备可以工作回调
新增服务端配置

4.1.9 版本已经在 9/5/2022 发布:¶

修复当发送UUID设置错误时应用闪退

4.1.8 版本已经在 14/4/2022 发布:¶

修复 autoOpenDiscoveryActivity 始终为 true
DiscoveryActivity 添加英文
添加 setDiscoveryTime

赞助¶

SerialPort 是采用 Apache-2.0 许可的开源项目，使用完全免费，但您的赞助可以使 SerialPort 获得更健康稳定的发展。

如果您认可作者的努力或者 SerialPort 确实帮助到了您，请到 Gitee和 GitHub上点个 Star 鼓励一下吧。另外如果您口袋充裕，可以扫以下的赞助码，成为 SerialPort 的赞助人：

_images/wx.png

Welcome to SerialPort’s documentation!¶

安装¶

快速上手 (Kotlin)¶

构建SerialPort实例¶

搜索设备¶

连接设备¶

设置传统设备UUID¶

设置BLE设备UUID¶

建立连接¶

接收消息¶

发送消息¶

快速上手 (Java)¶

构建SerialPort实例¶

搜索设备¶

连接设备¶

设置传统设备UUID¶

设置BLE设备UUID¶

建立连接¶

接收消息¶

发送消息¶

服务端¶

构建实例¶

打开服务¶

关闭服务¶

设置服务端可发现状态¶

断开连接¶

发送消息¶

配置¶

调试模式¶

自动重连¶

启动时重连¶

间隔自动重连¶

忽略无名设备¶

自动打开搜索界面¶

十六进制数据自动转换¶

内置搜索页面选择连接方式¶

配置器¶

设置搜索时长¶

搜索和连接¶

内置的界面¶

使用自定义的界面¶

搜索设备¶

开始搜索¶

停止搜索¶

搜索状态的监听¶

获取搜索结果¶

连接设备¶

传统设备¶

设置UUID¶

建立连接¶

BLE设备¶

设置UUID¶

建立连接¶

断开连接¶

连接状态的监听¶

BLE 可以工作回调¶

收发数据¶

设置数据格式¶

设置接收消息格式¶

设置发送数据格式¶

接收消息¶

字符串 和 十六进制¶

字节数组¶

发送消息¶

字符串¶

十六进制¶

BLE设备发送字节数组¶

Toast提示设置¶

配置方法¶

可选配置项¶

工具¶

打印UUID及其属性¶

字符串转换成十六进制¶

字节数组按要求的编码格式转换成字符串¶

字符串按要求的编码格式转换成字节数组¶

配置¶

调试模式¶

自动重连¶

启动时重连¶

间隔自动重连¶

字符串和十六进制¶

字符串和十六进制¶

English ¶

简体中文 ¶