Files
ch34/docs/CH34X-api_docs.md
2026-04-21 12:57:40 +08:00

704 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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>0vMin>0 时read 函数将阻塞直到读到最后一个字符时开始计时,超过 vTime 时间后,如果接收到的数据不足 vMin 字节,则返回。否则继续等待直到收到 vMin 个字节或超时。
2. 当 vTime>0vMin=0 时read 函数立即返回,超时为每个字符等待 vTime 时间。
3. 当 vTime=0vMin>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