377 lines
11 KiB
Markdown
377 lines
11 KiB
Markdown
# CH934X 系列芯片串口 Android 程序开发说明
|
||
|
||
## 目录
|
||
|
||
- [1 概述](#1-概述)
|
||
- [2 权限申请](#2-权限申请)
|
||
- [3 引入 SDK](#3-引入-sdk)
|
||
- [4 设备查找](#4-设备查找)
|
||
- [4.1 UsbHelper](#41-usbhelper)
|
||
- [5 设备打开与关闭](#5-设备打开与关闭)
|
||
- [5.1 打开设备](#51-打开设备)
|
||
- [5.2 关闭设备](#52-关闭设备)
|
||
- [6 串口读写](#6-串口读写)
|
||
- [6.1 读数据](#61-读数据)
|
||
- [6.2 写数据](#62-写数据)
|
||
- [7 其他接口](#7-其他接口)
|
||
- [7.1 GPIO 接口](#71-gpio-接口)
|
||
- [7.2 Modem 控制接口](#72-modem-控制接口)
|
||
- [7.3 异常接口](#73-异常接口)
|
||
- [8 接口总览](#8-接口总览)
|
||
- [9 更新日志](#9-更新日志)
|
||
|
||
---
|
||
|
||
## 1 概述
|
||
|
||
CH934X 是 USB 转串口芯片，支持多路串口。CH934X 提供了 Android 端 SDK，本文档主要介绍在 Android 平台进行串口程序开发所用到的接口。
|
||
|
||
CH934X 库接口主要分为以下几类：基本操作、设备查找、串口读写、其他接口、异常接口等。下文将以 API 形式介绍这些接口。
|
||
|
||
## 2 权限申请
|
||
|
||
需要在 AndroidManifest.xml 中添加 USB 权限申请：
|
||
|
||
```xml
|
||
<!-- 在 manifest 节点下添加 uses-feature -->
|
||
<uses-feature android:name="android.hardware.usb.host" android:required="true" />
|
||
```
|
||
|
||
需要在 Activity 启动之前（即 onCreate 函数中）添加以下代码来动态申请权限：
|
||
|
||
```java
|
||
// 申请权限，接收广播
|
||
UsbManager usbManager = (UsbManager) context.getSystemService(Context.USB_SERVICE);
|
||
// 申请权限
|
||
PendingIntent mPermissionIntent = PendingIntent.getBroadcast(context, 0, new Intent(ACTION_DEVICE_PERMISSION), 0);
|
||
IntentFilter filter = new IntentFilter(ACTION_DEVICE_PERMISSION);
|
||
context.registerReceiver(mUsbPermissionReceiver, filter);
|
||
// 获取 usb 设备列表并依次申请权限
|
||
HashMap<String, UsbDevice> deviceList = usbManager.getDeviceList();
|
||
for (UsbDevice device : deviceList.values()) {
|
||
usbManager.requestPermission(device, mPermissionIntent);
|
||
}
|
||
```
|
||
|
||
```java
|
||
// 接收权限申请广播
|
||
private static final String ACTION_DEVICE_PERMISSION = "com.example.USB_PERMISSION";
|
||
private final BroadcastReceiver mUsbPermissionReceiver = new BroadcastReceiver() {
|
||
public void onReceive(Context context, Intent intent) {
|
||
String action = intent.getAction();
|
||
if (ACTION_DEVICE_PERMISSION.equals(action)) {
|
||
synchronized (this) {
|
||
UsbDevice device = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);
|
||
if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) {
|
||
if (device != null) {
|
||
// 用户授权，可以进行设备打开等操作
|
||
}
|
||
} else {
|
||
Log.d(TAG, "permission denied for device " + device);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
};
|
||
```
|
||
|
||
## 3 引入 SDK
|
||
|
||
将 CH934XLib.jar 引入到工程，可放置在 app/libs/ 目录下，然后修改 app 模块的 build.gradle：
|
||
|
||
```gradle
|
||
dependencies {
|
||
implementation fileTree(dir: 'libs', include: ['*.jar'])
|
||
// ... 其他依赖
|
||
}
|
||
```
|
||
|
||
## 4 设备查找
|
||
|
||
CH934X 设备主要为 USB 转串口芯片，因此可以通过 Android USB Host API 来枚举设备。用户也可以使用 CH934X SDK 提供的 UsbHelper 工具类，简化设备枚举流程。
|
||
|
||
### 4.1 UsbHelper
|
||
|
||
通过 UsbHelper 工具类，获取 CH934X 设备的序列号及对应设备类，从而实现对 CH934X 设备与串口的精确查找。
|
||
|
||
#### 4.1.1 CH934XSerialNum
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public static String CH934XSerialNum(UsbDevice device)
|
||
```
|
||
|
||
- 参数：device，UsbDevice 对象。
|
||
- 返回值：String 类型，CH934X 设备序列号。如果设备不是 CH934X 设备，则返回 null。
|
||
- 说明：通过 USB 设备获取 CH934X 序列号。
|
||
|
||
#### 4.1.2 CH934XDeviceType
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public static int CH934XDeviceType(UsbDevice device)
|
||
```
|
||
|
||
- 参数：device，UsbDevice 对象。
|
||
- 返回值：int 类型，CH934X 设备类型。返回值为下表中的常量：
|
||
|
||
| 常量 | 值 | 描述 |
|
||
| -------------------------- | --- | ----------------------------- |
|
||
| DEVICE_TYPE_CH9344 | 0 | CH9344 芯片 |
|
||
| DEVICE_TYPE_CH9344L | 1 | CH9344L 芯片 |
|
||
| DEVICE_TYPE_CH9350 | 2 | CH9350 芯片 |
|
||
| DEVICE_TYPE_CH9348Q | 3 | CH9348Q 芯片 |
|
||
| DEVICE_TYPE_CH9342 | 4 | CH9342 芯片 |
|
||
| DEVICE_TYPE_CH934X_OTHER | 5 | 其他 CH934X 设备 |
|
||
|
||
- 说明：通过 USB 设备获取 CH934X 设备类型。
|
||
|
||
#### 4.1.3 getCH934XSerialPortList
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public static UsbSerial[] getCH934XSerialPortList(Context context, UsbDevice device, int interfaceNum)
|
||
```
|
||
|
||
- 参数：
|
||
- context，Context 对象。
|
||
- device，UsbDevice 对象。
|
||
- interfaceNum，int 类型，CH934X 设备的接口号。
|
||
- 返回值：UsbSerial 数组。
|
||
- 说明：获取 CH934X 设备的串口列表。
|
||
|
||
#### 4.1.4 getCH934XDeviceList
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public static List<CH934XDeviceInfo> getCH934XDeviceList(Context context)
|
||
```
|
||
|
||
- 参数：context，Context 对象。
|
||
- 返回值：List<CH934XDeviceInfo>，CH934X 设备信息列表。
|
||
- 说明：获取 CH934X 设备列表。
|
||
|
||
## 5 设备打开与关闭
|
||
|
||
### 5.1 打开设备
|
||
|
||
#### 5.1.1 init
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public boolean init(Context context, UsbDevice device, int interfaceNum, int serialPortIndex)
|
||
```
|
||
|
||
- 参数：
|
||
- context，Context 对象。
|
||
- device，UsbDevice 对象。
|
||
- interfaceNum，int 类型，CH934X 设备的接口号。
|
||
- serialPortIndex，int 类型，串口索引。
|
||
- 返回值：boolean 类型，true 表示成功，false 表示失败。
|
||
- 说明：初始化 CH934X 设备并打开指定串口。
|
||
|
||
```java
|
||
// 示例代码
|
||
UsbSerial serialPort = new UsbSerial();
|
||
if (serialPort.init(context, device, interfaceNum, serialPortIndex)) {
|
||
// 初始化成功
|
||
}
|
||
```
|
||
|
||
### 5.2 关闭设备
|
||
|
||
#### 5.2.1 close
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public boolean close()
|
||
```
|
||
|
||
- 返回值：boolean 类型，true 表示成功，false 表示失败。
|
||
- 说明：关闭串口。
|
||
|
||
```java
|
||
// 示例代码
|
||
if (serialPort != null) {
|
||
serialPort.close();
|
||
serialPort = null;
|
||
}
|
||
```
|
||
|
||
## 6 串口读写
|
||
|
||
### 6.1 读数据
|
||
|
||
#### 6.1.1 read
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public int read(byte[] buf, int length)
|
||
```
|
||
|
||
- 参数：
|
||
- buf，byte[] 类型，接收数据的缓冲区。
|
||
- length，int 类型，要读取的字节数。
|
||
- 返回值：int 类型，实际读取的字节数；返回 0 或负值表示无数据或读取失败。
|
||
- 说明：从串口读取数据。
|
||
|
||
```java
|
||
// 示例代码
|
||
byte[] buffer = new byte[1024];
|
||
int length = serialPort.read(buffer, buffer.length);
|
||
if (length > 0) {
|
||
// 处理读取到的数据
|
||
}
|
||
```
|
||
|
||
### 6.2 写数据
|
||
|
||
#### 6.2.1 write
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public int write(byte[] buf, int length)
|
||
```
|
||
|
||
- 参数：
|
||
- buf，byte[] 类型，要发送的数据。
|
||
- length，int 类型，要发送的字节数。
|
||
- 返回值：int 类型，实际写入的字节数；返回 0 或负值表示写入失败。
|
||
- 说明：向串口写入数据。
|
||
|
||
```java
|
||
// 示例代码
|
||
byte[] data = new byte[]{0x01, 0x02, 0x03};
|
||
int length = serialPort.write(data, data.length);
|
||
if (length > 0) {
|
||
// 写入成功
|
||
}
|
||
```
|
||
|
||
## 7 其他接口
|
||
|
||
### 7.1 GPIO 接口
|
||
|
||
#### 7.1.1 setGpioOutput
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public boolean setGpioOutput(int gpioNum, int level)
|
||
```
|
||
|
||
- 参数：
|
||
- gpioNum，int 类型，GPIO 引脚编号。
|
||
- level，int 类型，输出电平（0 或 1）。
|
||
- 返回值：boolean 类型，true 表示成功，false 表示失败。
|
||
- 说明：设置 GPIO 引脚为输出模式并设置电平。
|
||
|
||
#### 7.1.2 getGpioInput
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public int getGpioInput(int gpioNum)
|
||
```
|
||
|
||
- 参数：gpioNum，int 类型，GPIO 引脚编号。
|
||
- 返回值：int 类型，输入电平（0 或 1），负值表示读取失败。
|
||
- 说明：读取 GPIO 引脚输入电平。
|
||
|
||
### 7.2 Modem 控制接口
|
||
|
||
#### 7.2.1 setModemControl
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public boolean setModemControl(int dtr, int rts)
|
||
```
|
||
|
||
- 参数：
|
||
- dtr，int 类型，DTR 信号电平（0 或 1）。
|
||
- rts，int 类型，RTS 信号电平（0 或 1）。
|
||
- 返回值：boolean 类型，true 表示成功，false 表示失败。
|
||
- 说明：设置 DTR 和 RTS 信号。
|
||
|
||
#### 7.2.2 getModemStatus
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public int getModemStatus()
|
||
```
|
||
|
||
- 返回值：int 类型，Modem 状态位。返回值为下表中的位掩码：
|
||
|
||
| 常量 | 值 | 描述 |
|
||
| --------------------- | ----- | ---------- |
|
||
| MODEM_STATUS_CTS | 0x01 | CTS 状态 |
|
||
| MODEM_STATUS_DSR | 0x02 | DSR 状态 |
|
||
| MODEM_STATUS_RI | 0x04 | RI 状态 |
|
||
| MODEM_STATUS_DCD | 0x08 | DCD 状态 |
|
||
|
||
- 说明：获取 Modem 状态。
|
||
|
||
```java
|
||
// 示例代码
|
||
int status = serialPort.getModemStatus();
|
||
boolean cts = (status & UsbSerial.MODEM_STATUS_CTS) != 0;
|
||
```
|
||
|
||
### 7.3 异常接口
|
||
|
||
#### 7.3.1 setExceptionCallback
|
||
|
||
- 函数原型：
|
||
|
||
```java
|
||
public void setExceptionCallback(UsbSerial.ExceptionCallback callback)
|
||
```
|
||
|
||
- 参数：callback，ExceptionCallback 对象，异常回调接口。
|
||
- 返回值：无。
|
||
- 说明：设置异常回调，用于接收设备拔出等异常事件。
|
||
|
||
```java
|
||
// 示例代码
|
||
serialPort.setExceptionCallback(new UsbSerial.ExceptionCallback() {
|
||
@Override
|
||
public void onException(int type, Exception e) {
|
||
// 处理异常，例如设备拔出
|
||
}
|
||
});
|
||
```
|
||
|
||
## 8 接口总览
|
||
|
||
| 接口 | 名称 | 分类 | 说明 |
|
||
| ---- | ---- | ---- | ---- |
|
||
| UsbHelper.CH934XSerialNum | 获取 CH934X 序列号 | 设备查找 | 获取 CH934X 设备的序列号 |
|
||
| UsbHelper.CH934XDeviceType | 获取 CH934X 设备类型 | 设备查找 | 获取 CH934X 设备的类型 |
|
||
| UsbHelper.getCH934XSerialPortList | 获取 CH934X 串口列表 | 设备查找 | 获取指定 CH934X 设备的串口列表 |
|
||
| UsbHelper.getCH934XDeviceList | 获取 CH934X 设备列表 | 设备查找 | 获取所有 CH934X 设备列表 |
|
||
| UsbSerial.init | 初始化并打开串口 | 设备打开 | 初始化并打开指定串口 |
|
||
| UsbSerial.close | 关闭串口 | 设备关闭 | 关闭已打开的串口 |
|
||
| UsbSerial.read | 读取数据 | 串口读写 | 从串口读取数据 |
|
||
| UsbSerial.write | 写入数据 | 串口读写 | 向串口写入数据 |
|
||
| UsbSerial.setGpioOutput | 设置 GPIO 输出 | GPIO | 设置 GPIO 引脚为输出模式并设置电平 |
|
||
| UsbSerial.getGpioInput | 读取 GPIO 输入 | GPIO | 读取 GPIO 引脚输入电平 |
|
||
| UsbSerial.setModemControl | 设置 Modem 控制 | Modem | 设置 DTR 和 RTS 信号 |
|
||
| UsbSerial.getModemStatus | 获取 Modem 状态 | Modem | 获取 Modem 状态 |
|
||
| UsbSerial.setExceptionCallback | 设置异常回调 | 异常 | 设置设备拔出等异常回调 |
|
||
|
||
## 9 更新日志
|
||
|
||
| 版本 | 日期 | 更新内容 |
|
||
| ---- | ---- | -------- |
|
||
| 1.0 | 2024-08-15 | 初版发布，包含 CH934X 设备查找、串口读写、GPIO、Modem 控制、异常回调等接口 |
|