# 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

```java
public static WCHUARTManager getInstance()
```

用于获取全局唯一实例。

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

---

### 4.2 init

```java
public void init(android.app.Application application)
```

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

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

---

### 4.3 enumDevice

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

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

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

---

### 4.4 getChipType

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

获取 usbDevice 的芯片类型。

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

---

### 4.5 openDevice

```java
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<br>cn.wch.uartlib.exception.NoPermissionException<br>cn.wch.uartlib.exception.ChipException |

---

### 4.6 requestPermission

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

请求 USB 设备权限。

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

---

### 4.7 setUsbStateListener

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

监听设备的状态变化。

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

---

### 4.8 getSerialCount

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

获取设备串口数量。

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

---

### 4.9 enableSerial

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

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

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

---

### 4.10 setSerialParameter

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

---

### 4.11 getSerialBaud

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

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

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

---

### 4.12 getChipMasterFrequency

```java
public ChipMasterFrequency getChipMasterFrequency(@NonNull UsbDevice
        usbDevice) throws Exception
```

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

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

---

### 4.13 syncWriteData

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

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

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

---

### 4.14 asyncWriteData

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

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

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

---

### 4.15 readData

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

读取串口数据。

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

---

### 4.16 readData（重载方法）

```java
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 设备<br>serialNumber - 串口号<br>vTime - 等待时间<br>vMin - 最小读取字节数 |
| 返回 | 读取到的数据 |
| 抛出 | cn.wch.uartlib.exception.ChipException |

---

### 4.17 registerDataCallback

```java
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 设备<br>dataCallback - 数据回调 |
| 抛出 | java.lang.Exception |

---

### 4.18 removeDataCallback

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

移除串口数据回调。

| 项目 | 说明 |
|------|------|
| 参数 | usbDevice - USB 设备 |

---

### 4.19 isConnected

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

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

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

---

### 4.20 getConnectedDevices

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

获取当前已连接的设备。

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

---

### 4.21 disconnect

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

断开 USB 设备连接。

| 项目 | 说明 |
|------|------|
| 参数 | usbDevice - USB 设备 |

---

### 4.22 close

```java
public void close(@NonNull Context context)
```

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

| 项目 | 说明 |
|------|------|
| 参数 | context - 上下文 |

---

### 4.23 isSupportGPIOFeature

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

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

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

---

### 4.24 queryGPIOCount

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

查询该 USB 设备的 GPIO 数量。

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

---

### 4.25 queryGPIOStatus

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

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

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

---

### 4.26 queryAllGPIOStatus

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

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

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

---

### 4.27 enableGPIO

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

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

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

---

### 4.28 setGPIOVal

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

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

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

---

### 4.29 getGPIOVal

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

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

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

---

### 4.30 setDTR

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

设置 DTR 信号。

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

---

### 4.31 setRTS

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

设置 RTS 信号。

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

---

### 4.32 setBreak

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

设置 Break 信号。

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

---

### 4.33 registerModemStatusCallback

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

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

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

---

### 4.34 querySerialErrorCount

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

查询串口错误状态。

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

---

### 4.35 setReadTimeout

```java
public static void setReadTimeout(int timeout)
```

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

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

---

### 4.36 addNewHardwareAndChipType

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

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

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

---

### 4.37 setDebug

```java
public static void setDebug(boolean open)
```

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

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

---

### 4.38 isDebugMode

```java
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