huangsheng/ch34
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ch34/docs/CH34X-api_docs.md
leon c000eb12f8 1
2026-04-21 12:57:40 +08:00

18 KiB
Raw Permalink Blame History

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

版本：1.8

https://wch.cn

一、简介

本文档适用于 CH339 / CH340 / CH341 / CH342 / CH343 / CH344 / CH347 / CH9101 / CH9102 / CH9103 / CH9104 / CH9143 / CH9111 / CH9114 的 USB 转串口芯片开发说明。

本文档其余部分均以 CH340 系列 USB 转异步串口功能（以下简称 CH34XUART）以及 GPIO 功能，以及 Android 4.4 和更新版本的系统进行说明。在功能基于 USB Host 实现连接，用户需调用相应的 API 实现与 Android 设备进行数据交互。

Android Host 和 USB Device 的通讯关系参考图：

USB HOST          USB Device
Android (USB HOST/OTG) ─── USB 通讯 ─── 转接芯片 ─── UART ─── PC/MCU/串口设备

CH34X 串口转接芯片 Android 接口需要 Android 4.4 及以上版本系统，使用 CH34X 需要 Android 满足条件：

  1. 基于 Android 4.4 及以上版本系统
  2. Android 设备具备 USB Host（或 OTG）接口

本文档将着重介绍调用 Android USB Host 与 Device 通讯相关 API 以及相应的操作说明。关于 Android USB Host 协议说明，可以参考 Google 官方文档。

二、Android Host

本文档所指的程序是基于 Android 4.4 及以上版本系统下编写的。Android 应用程序的动画参考文章 Android Filter.xml 文件的 product id 和 vendor id，基于 CH34X UART 开发的 Android 应用程序主要架构和步骤，如下图：

┌──────────────────────────────┐
│        Android Host          │
│  ┌──────────────────────┐    │
│  │    User Layout       │    │
│  └──────────────────────┘    │
│                              │
│  ┌──────────────────────┐    │
│  │    CH34XUART         │    │
│  │    Applications      │    │
│  └──────────────────────┘    │
│          ↕                   │
│  ┌──────────────────────┐    │
│  │  CH34XDriver.jar (lib)│   │
│  └──────────────────────┘    │
└──────────────────────────────┘

三、软件操作说明

用户需要在支持 USB Host 功能的 Android 设备上安装测试程序（CH34XUARTDemo.apk），点击打开测试程序，测试程序显示当前 USB 设备的状态。点击"打开"后，如果未连接相应的 USB 芯片的设备，则会显示设备未连接状态；点击"断开"，则会显示设备未连接。在连接条件后，按钮显示"已连接"。用户通过串口调试功能，发送数据可以接收返回的数据。

四、函数接口说明

4.1 getInstance

public static WCHUARTManager getInstance()

用于获取全局唯一实例。

项目 说明
返回 返回全局唯一实例

4.2 init

public void init(android.app.Application application)

初始化上下文，注册广播接收设备状态变化。

项目 说明
参数 application - 全局上下文

4.3 enumDevice

public java.util.ArrayList<android.hardware.usb.UsbDevice> enumDevice()
        throws java.lang.Exception

枚举当前所有符合要求的 USB 设备。

项目 说明
返回 android.hardware.usb.UsbDevice 设备列表
抛出 java.lang.Exception

4.4 getChipType

public cn.wch.uartlib.chipImpl.type.ChipType2 getChipType(@NonNull
        android.hardware.usb.UsbDevice usbDevice)

获取 usbDevice 的芯片类型。

项目 说明
参数 usbDevice - USB 设备
返回 芯片类型（usbDevice 是 WCH 芯片）；否则表示无法识别 USB 设备的芯片类型

4.5 openDevice

public boolean openDevice(@NonNull
        android.hardware.usb.UsbDevice usbDevice)
        throws cn.wch.uartlib.exception.UartLibException,
               cn.wch.uartlib.exception.NoPermissionException,
               cn.wch.uartlib.exception.ChipException

打开 USB 设备。

项目 说明
参数 usbDevice - USB 设备
返回 true 成功；false 失败
抛出 cn.wch.uartlib.exception.UartLibException
cn.wch.uartlib.exception.NoPermissionException
cn.wch.uartlib.exception.ChipException

4.6 requestPermission

public void requestPermission(@NonNull
        android.content.Context context,
        @NonNull android.hardware.usb.UsbDevice usbDevice)
        throws cn.wch.uartlib.exception.UartLibException

请求 USB 设备权限。

项目 说明
参数 context - 上下文
usbDevice - USB 设备
抛出 cn.wch.uartlib.exception.UartLibException

4.7 setUsbStateListener

public void setUsbStateListener(@NonNull
        cn.wch.uartlib.callback.IUsbStateChange usbStateListener)

监听设备的状态变化。

项目 说明
参数 usbStateListener - 设备状态监听回调

4.8 getSerialCount

public int getSerialCount(@NonNull
        android.hardware.usb.UsbDevice usbDevice)

获取设备串口数量。

项目 说明
参数 usbDevice - USB 设备
返回 返回串口数量。如果为负数，说明获取芯片类型失败

4.9 enableSerial

public boolean enableSerial(@NonNull UsbDevice usbDevice,
        int serialNumber, boolean enable) throws Exception

打开/关闭串口（实际仅对 CH9114 系列有效，其他类型设备无影响）。

项目 说明
参数 usbDevice - USB 设备
serialNumber - 串口号
enable - false 关闭；true 打开
返回 true 设置成功；false 设置失败
抛出 java.lang.Exception

4.10 setSerialParameter

public boolean setSerialParameter(@NonNull
        android.hardware.usb.UsbDevice usbDevice,
        int serialNumber,
        int baud,
        int dataBit,
        int stopBit,
        int parityBit,
        boolean flow)
        throws java.lang.Exception

设置串口参数。

项目 说明
参数 usbDevice - USB 设备
serialNumber - 串口号
baud - 波特率
dataBit - 数据位 5,6,7,8
stopBit - 停止位 1,2
parityBit - 校验位 0 NONE; 1 ODD; 2 EVEN; 3 MARK; 4 SPACE
flow - true 打开流控；false 关闭
返回 true 设置成功；false 设置失败
抛出 java.lang.Exception

4.11 getSerialBaud

public int getSerialBaud(@NonNull UsbDevice usbDevice, int serialNumber)
        throws Exception

获取串口波特率（实际仅对 CH9114 系列有效，其他类型设备无影响）。

项目 说明
参数 usbDevice - USB 设备
serialNumber - 串口号
返回 大于 0：串口波特率；小于 0：出错
抛出 java.lang.Exception

4.12 getChipMasterFrequency

public ChipMasterFrequency getChipMasterFrequency(@NonNull UsbDevice
        usbDevice) throws Exception

获取芯片主频（实际仅对 CH9114 系列有效，其他类型设备无影响）。

项目 说明
参数 usbDevice - USB 设备
返回 ChipMasterFrequency 对象：
- int frequency 频率
- Boolean switchEnable 是否允许切换
- int CoStatus 当前状态
抛出 java.lang.Exception

4.13 syncWriteData

public int syncWriteData(@NonNull UsbDevice usbDevice, int serialNumber,
        byte[] data, int length, int timeout) throws Exception

发送串口数据（同步发送）。

项目 说明
参数 usbDevice - USB 设备
serialNumber - 串口号
data - 将要发送的数据
length - 将要发送数据的长度
timeout - 超时时间
返回 发送成功返回数据的长度
抛出 java.lang.Exception

4.14 asyncWriteData

public void asyncWriteData(@NonNull UsbDevice usbDevice, int serialNumber,
        byte[] data) throws Exception

发送串口数据（异步发送，将数据加入缓存队列发送，不能返回状态和结果）。

项目 说明
参数 usbDevice - USB 设备
serialNumber - 串口号
data - 将要发送的数据
抛出 java.lang.Exception

4.15 readData

public byte[] readData(@NonNull
        android.hardware.usb.UsbDevice usbDevice,
        int serialNumber)
        throws java.lang.Exception

读取串口数据。

项目 说明
参数 usbDevice - USB 设备
serialNumber - 串口号
返回 读取到的数据
抛出 cn.wch.uartlib.exception.ChipException

4.16 readData（重载方法）

public byte[] readData(@NonNull
        android.hardware.usb.UsbDevice usbDevice,
        int serialNumber,
        int vTime,
        int vMin)
        throws java.lang.Exception

读取串口数据。

说明：

  1. 当 vTime>0，vMin>0 时，read 函数将阻塞直到读到最后一个字符时开始计时，超过 vTime 时间后，如果接收到的数据不足 vMin 字节，则返回。否则继续等待直到收到 vMin 个字节或超时。
  2. 当 vTime>0，vMin=0 时，read 函数立即返回，超时为每个字符等待 vTime 时间。
  3. 当 vTime=0，vMin>0 时，read 函数一直阻塞，直到读到 vMin 个字节后返回。
项目 说明
参数 usbDevice - USB 设备
serialNumber - 串口号
vTime - 等待时间
vMin - 最小读取字节数
返回 读取到的数据
抛出 cn.wch.uartlib.exception.ChipException

4.17 registerDataCallback

public void registerDataCallback (@NonNull
        android.hardware.usb.UsbDevice usbDevice,
        cn.wch.uartlib.callback.IDataCallback dataCallback)
        throws java.lang.Exception

注册串口数据回调（此方法可替代 readData 函数，用户通过回调方式接收数据）。注意：如果调用了 registerDataCallback(device,null)，等同于 removeDataCallback(device)。

项目 说明
参数 usbDevice - USB 设备
dataCallback - 数据回调
抛出 java.lang.Exception

4.18 removeDataCallback

public void removeDataCallback (@NonNull
        android.hardware.usb.UsbDevice usbDevice)

移除串口数据回调。

项目 说明
参数 usbDevice - USB 设备

4.19 isConnected

public boolean isConnected(@NonNull
        android.hardware.usb.UsbDevice usbDevice)

判断 USB 设备是否已经连接。

项目 说明
参数 usbDevice - USB 设备
返回 true 已经连接；false 没有打开

4.20 getConnectedDevices

public java.util.ArrayList<android.hardware.usb.UsbDevice> getConnectedDevices()

获取当前已连接的设备。

项目 说明
返回 已经打开的设备列表

4.21 disconnect

public void disconnect(@NonNull
        android.hardware.usb.UsbDevice usbDevice)

断开 USB 设备连接。

项目 说明
参数 usbDevice - USB 设备

4.22 close

public void close(@NonNull Context context)

释放资源、断开所有连接设备。

项目 说明
参数 context - 上下文

4.23 isSupportGPIOFeature

public boolean isSupportGPIOFeature(UsbDevice device)
        throws java.lang.Exception

检查本接口当前是否支持该设备的 GPIO 特性配置。应当在操作 GPIO 前调用。

项目 说明
参数 device - USB 设备
返回 true 支持；false 不支持
抛出 java.lang.Exception

4.24 queryGPIOCount

public int queryGPIOCount(UsbDevice device)
        throws java.lang.Exception

查询该 USB 设备的 GPIO 数量。

项目 说明
参数 device - USB 设备
返回 GPIO 数量
抛出 java.lang.Exception

4.25 queryGPIOStatus

public GPIO_Status queryGPIOStatus(UsbDevice device, int gpioIndex)
        throws java.lang.Exception

查询该 USB 设备的某个 GPIO 状态。

项目 说明
参数 device - USB 设备
gpioIndex - GPIO 序号，从 0 开始
返回 GPIO 状态
抛出 java.lang.Exception

4.26 queryAllGPIOStatus

public List<GPIO_Status> queryAllGPIOStatus(UsbDevice device)
        throws java.lang.Exception

查询该 USB 设备的全部 GPIO 状态。

项目 说明
参数 device - USB 设备
返回 全部 GPIO 状态
抛出 java.lang.Exception

4.27 enableGPIO

public boolean enableGPIO(UsbDevice device, int gpioIndex, boolean enable,
        GPIO_DIR dir)
        throws java.lang.Exception

使能该硬件设备的某个 GPIO。

项目 说明
参数 device - USB 设备
gpioIndex - GPIO 序号
enable - true 打开；false 关闭
dir - GPIO 方向
抛出 java.lang.Exception

4.28 setGPIOVal

public boolean setGPIOVal(UsbDevice device, int gpioIndex, GPIO_VALUE value)
        throws java.lang.Exception

设置该硬件设备的某个 GPIO 的电平值。

项目 说明
参数 device - USB 设备
gpioIndex - GPIO 序号
value - GPIO 电平值
返回 true 操作成功；false 操作失败
抛出 java.lang.Exception

4.29 getGPIOVal

public GPIO_VALUE getGPIOVal(UsbDevice device, int gpioIndex)
        throws java.lang.Exception

获取该硬件设备的某个 GPIO 的电平值。

项目 说明
参数 device - USB 设备
gpioIndex - GPIO 序号
返回 value - GPIO 电平值
抛出 java.lang.Exception

4.30 setDTR

public boolean setDTR(@NonNull UsbDevice usbDevice, int serialNumber, boolean valid)
        throws Exception

设置 DTR 信号。

项目 说明
参数 device - USB 设备
serialNumber - 串口号
valid - 是否有效（低电平有效）
返回 true 操作成功；false 操作失败
抛出 java.lang.Exception

4.31 setRTS

public boolean setRTS(@NonNull UsbDevice usbDevice, int serialNumber, boolean valid)
        throws Exception

设置 RTS 信号。

项目 说明
参数 device - USB 设备
serialNumber - 串口号
valid - 是否有效（低电平有效）
返回 true 操作成功；false 操作失败
抛出 java.lang.Exception

4.32 setBreak

public boolean setBreak(@NonNull UsbDevice usbDevice, int serialNumber, boolean valid)
        throws Exception

设置 Break 信号。

项目 说明
参数 device - USB 设备
serialNumber - 串口号
valid - 是否有效（低电平有效）
返回 true 操作成功；false 操作失败
抛出 java.lang.Exception

4.33 registerModemStatusCallback

public void registerModemStatusCallback(@NonNull UsbDevice usbDevice, IModemStatus
        modemStatus) throws Exception

注册 Modem 输入信号状态的回调。

项目 说明
参数 device - USB 设备
modemStatus - 状态回调
抛出 java.lang.Exception

4.34 querySerialErrorCount

public int querySerialErrorCount(@NonNull UsbDevice usbDevice, int
        serialNumber, @NonNull SerialErrorType errorType) throws Exception

查询串口错误状态。

项目 说明
参数 device - USB 设备
serialNumber - 串口号
errorType - 错误类型
返回 该种错误的次数
抛出 java.lang.Exception

4.35 setReadTimeout

public static void setReadTimeout(int timeout)

设置读超时时间。默认为 0，即采用异步方式读取；设置为非 0 时采用同步方式，超时时间为 BulkTransfer 同步传输的超时时间。全局生效，应在 APP 初始化时设置。

项目 说明
参数 timeout - 超时时间，单位为 ms

4.36 addNewHardwareAndChipType

public static void addNewHardwareAndChipType(int vid, int pid, ChipType2 chipType)

添加新的硬件 VID/PID 以及芯片类型。

项目 说明
参数 vid - 硬件 vid
pid - 硬件 pid
chipType - 芯片类型

4.37 setDebug

public static void setDebug(boolean open)

设置调试模式打开或者关闭。打开调试模式会打印日志，默认关闭。应在 APP 初始化时设置。

项目 说明
参数 open - true 打开；false 关闭

4.38 isDebugMode

public static boolean isDebugMode()

返回当前是否在调试模式，是否打印日志。

项目 说明
返回 true 处于调试模式；false 不处于调试模式

附录

  • 文档版本： V1.8
  • 文档名称： CH34X 系列芯片串口 Android 程序开发说明
  • 适用芯片型号： CH339 / CH340 / CH341 / CH342 / CH343 / CH344 / CH347 / CH9101 / CH9102 / CH9103 / CH9104 / CH9143 / CH9111 / CH9114
  • 系统要求： Android 4.4 及以上版本
  • 技术支持网站： https://wch.cn
Reference in New Issue View Git Blame Copy Permalink