huangsheng/ch934x_serial

Fork 0

Files

T

Developer 6efaf5671f init

2026-07-06 15:37:22 +08:00

11 KiB

Raw Blame History

CH934X 系列芯片串口 Android 程序开发说明

1 概述

CH934X 是 USB 转串口芯片，支持多路串口。CH934X 提供了 Android 端 SDK，本文档主要介绍在 Android 平台进行串口程序开发所用到的接口。

CH934X 库接口主要分为以下几类：基本操作、设备查找、串口读写、其他接口、异常接口等。下文将以 API 形式介绍这些接口。

2 权限申请

需要在 AndroidManifest.xml 中添加 USB 权限申请：

<!-- 在 manifest 节点下添加 uses-feature -->
<uses-feature android:name="android.hardware.usb.host" android:required="true" />

需要在 Activity 启动之前（即 onCreate 函数中）添加以下代码来动态申请权限：

// 申请权限，接收广播
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);
}

// 接收权限申请广播
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：

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

函数原型：

public static String CH934XSerialNum(UsbDevice device)

参数：device，UsbDevice 对象。
返回值：String 类型，CH934X 设备序列号。如果设备不是 CH934X 设备，则返回 null。
说明：通过 USB 设备获取 CH934X 序列号。

4.1.2 CH934XDeviceType

函数原型：

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

函数原型：

public static UsbSerial[] getCH934XSerialPortList(Context context, UsbDevice device, int interfaceNum)

参数：
- context，Context 对象。
- device，UsbDevice 对象。
- interfaceNum，int 类型，CH934X 设备的接口号。
返回值：UsbSerial 数组。
说明：获取 CH934X 设备的串口列表。

4.1.4 getCH934XDeviceList

函数原型：

public static List<CH934XDeviceInfo> getCH934XDeviceList(Context context)

参数：context，Context 对象。
返回值：List，CH934X 设备信息列表。
说明：获取 CH934X 设备列表。

5 设备打开与关闭

5.1 打开设备

5.1.1 init

函数原型：

public boolean init(Context context, UsbDevice device, int interfaceNum, int serialPortIndex)

参数：
- context，Context 对象。
- device，UsbDevice 对象。
- interfaceNum，int 类型，CH934X 设备的接口号。
- serialPortIndex，int 类型，串口索引。
返回值：boolean 类型，true 表示成功，false 表示失败。
说明：初始化 CH934X 设备并打开指定串口。

// 示例代码
UsbSerial serialPort = new UsbSerial();
if (serialPort.init(context, device, interfaceNum, serialPortIndex)) {
    // 初始化成功
}

5.2 关闭设备

5.2.1 close

函数原型：

public boolean close()

返回值：boolean 类型，true 表示成功，false 表示失败。
说明：关闭串口。

// 示例代码
if (serialPort != null) {
    serialPort.close();
    serialPort = null;
}

6 串口读写

6.1 读数据

6.1.1 read

函数原型：

public int read(byte[] buf, int length)

参数：
- buf，byte[] 类型，接收数据的缓冲区。
- length，int 类型，要读取的字节数。
返回值：int 类型，实际读取的字节数；返回 0 或负值表示无数据或读取失败。
说明：从串口读取数据。

// 示例代码
byte[] buffer = new byte[1024];
int length = serialPort.read(buffer, buffer.length);
if (length > 0) {
    // 处理读取到的数据
}

6.2 写数据

6.2.1 write

函数原型：

public int write(byte[] buf, int length)

参数：
- buf，byte[] 类型，要发送的数据。
- length，int 类型，要发送的字节数。
返回值：int 类型，实际写入的字节数；返回 0 或负值表示写入失败。
说明：向串口写入数据。

// 示例代码
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

函数原型：

public boolean setGpioOutput(int gpioNum, int level)

参数：
- gpioNum，int 类型，GPIO 引脚编号。
- level，int 类型，输出电平（0 或 1）。
返回值：boolean 类型，true 表示成功，false 表示失败。
说明：设置 GPIO 引脚为输出模式并设置电平。

7.1.2 getGpioInput

函数原型：

public int getGpioInput(int gpioNum)

参数：gpioNum，int 类型，GPIO 引脚编号。
返回值：int 类型，输入电平（0 或 1），负值表示读取失败。
说明：读取 GPIO 引脚输入电平。

7.2 Modem 控制接口

7.2.1 setModemControl

函数原型：

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

函数原型：

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 状态。

// 示例代码
int status = serialPort.getModemStatus();
boolean cts = (status & UsbSerial.MODEM_STATUS_CTS) != 0;

7.3 异常接口

7.3.1 setExceptionCallback

函数原型：

public void setExceptionCallback(UsbSerial.ExceptionCallback callback)

参数：callback，ExceptionCallback 对象，异常回调接口。
返回值：无。
说明：设置异常回调，用于接收设备拔出等异常事件。

// 示例代码
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 控制、异常回调等接口

11 KiB Raw Blame History Unescape Escape