AN169USBXpressProgrammersGuide.docx
《AN169USBXpressProgrammersGuide.docx》由会员分享，可在线阅读，更多相关《AN169USBXpressProgrammersGuide.docx（18页珍藏版）》请在冰豆网上搜索。
AN169USBXpressProgrammersGuide
USBXPRESS程序开发指南
相关设备:
这个程序文档适用于以下设备:
C8051F32x,C8051F34x,C8051F38x,C8051T32x,C8051T62x,CP2101,CP2102,CP2103,CP2104,CP2105
1.简介
TheSiliconLaboratories的USBXpress®为C8051F32x,C8051F34x,C8051F38x,C8051T32x,和C8051T62xUSB微控制器和CP210x通信提了一个完整的主机和设备的软件解决方案.任何USB协议或主机设备驱动程序
需要的专业知识。
相反，一个简单的，高层次的应用程序接口（API）为主机软件
和设备固件是用来提供完整的USB连接。
USBXpress开发工具包包含Windows设备驱动、Windows设备驱动安装程序、主机接口、动态链接库、设备固件。
2.主机API函数
主机函数在动态链接库里提供。
主机接口DLL与USB通过设备驱动程序和操作系统的USB协议进行通信。
下面是一个可用的API函数列表:
SI_GetNumDevices（）－返回链接设备的数量
SI_GetProductString（）－返回设备的描述
SI_Open（）－打开设备并返回设备句柄
SI_Close（）-取消挂起的IO和关闭设备
SI_Read（）-重设备中读取一个数据块
SI_Write（）-往设备里写一个数据块
SI_FlushBuffers（）-刷新设备的接收与发送缓冲区
SI_SetTimeouts（）-设置读写数据块的超时时间
SI_GetTimeouts（）-读取读写数据块的超时时间
SI_CheckRXQueue（）-返回设备的接收队列中的字节数
SI_SetBaudRate（）-设定指定CP210x设备的波特率
SI_SetBaudDivisor（）-设定指定CP210x设备的波特率的分频值
SI_SetLineControl（）-设定指定CP210x设备的控制线
SI_SetFlowControl（）-设定指定CP210x设备的流量控制
SI_GetModemStatus（）-取得指定CP210x设备的调制解调器的状态
SI_SetBreak（）-设置CP210x设备的指定状态
SI_ReadLatch（）-获取CP210x设备的端口的锁存值
SI_WriteLatch（）-设置CP210x设备的端口的锁存值
SI_GetPartNumber（）-获取CP210x设备的型号
SI_DeviceIOControl（）-允许低级命令发送到设备驱动程序
SI_GetDLLVersion（）-取得当前正在使用的DLL版本
SI_GetDriverVersion（）-取得USBXpress驱动程序的版本
通常，用户使用SI_GetNumDevices（）函数开起设备进行通信。
主个调用将返回目标设备的数量。
这个数字用在SI_GetProductString（）函数上，用来返回一个设备的字符串形式的序列号。
要成功访问设备，必须通过SI_GetProductString（）返回的数据做为参数传递给SI_Open（）函数来找开设备。
SI_Open（）函数返回设备的句柄，为函数SI_Write（）与SI_Read（）这两个函数提供参数。
当I/O通信操作完成后，调用函数SI_Close（）函数数来关闭设备。
其他函数提供了刷新发送与接收缓冲区（SI_FlushBuffers）、设置与接收的超时时间（SI_SetTimeouts）、检查缓冲区的状态（SI_CheckRXQueue）、设备控制（SI_DeviceIOControl）
对于CP210x设备,提供了设置波特率（SI_SetBaudRate）的函数、设置波特率分频值（除数）（SI_SetBaudDivisior）;调整、如字长、停止位、奇偶行的控制设置（SI_SetLineControl）;设置硬件握手、软件握手和调制解调器控制信号（SI_SetFlowControl）;取得调制解调器状态（SI_GetModemStatus）。
CP2103/4/5附加功能函数取得设备端口（SI_ReadLatch）设置端口（SI_WriteLatch）设备上额外的可用GPIO馆脚值，通过SI_GetPartNumber（）返回的号码区分设备。
这些函数的功能将在下章详细介绍。
类型与常量定义在”附录C++头文件SiUSBXp.h”中。
2.1SI_GetNumDevices
描述:
这个函数返回设备的链接数
支持设备:
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型:
SI_STATUSSI_GetNumDevices（LPDWORDNumDevices）
参数:
1。
NumDevices:
一个DWORD类型的变量，返回的是存放设备数变量的地址
返回值:
SI_STATUS=SI_SUCCESSorSI_DEVICE_NOT_FOUNDorSI_INVALID_PARAMETER
2.2SI_GetProductString
描述：
这个函数返回一个不为空的序列号字符串或产品描述字符串，使用SI_GetNumDevices函数返回的数据。
通过参数DeviceNum指定设备。
第一个设备指数为0，
最后一台设备是由SI_GetNumDevices返回的值-1。
支持设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_GetProductString（DWORDDeviceNum,LPVOIDDeviceString,DWORDOption）
参数：
1DeviceNum:
设备唯一序列号或描述字符串
2DeviceString:
SI_DEVICE_STRING类型，返回一个设备描述符或字符串或一个代表终止的NULL。
3Options:
DWORD类型的标志，以确定是否在DeviceString中包含一个序列号。
产品说明，供应商ID，产品ID字符串。
请参见“附录D-定义从C++
头文件SiUSBXp.h“中的标志。
返回值：
SI_STATUS=SI_SUCCESSor
SI_DEVICE_NOT_FOUNDor
SI_INVALID_PARAMETER
2.3SI_Open
描述：
为以后访问打开一个设备（使用SI_GetNumDevices函数返回的设备号）并返回一个设备句柄。
支持的设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_Open（DWORDDeviceNum,HANDLE*Handle）
参数：
1DeviceNum:
设备的索引，从0开始
2Handle：
一个存放设备句柄的指针变量,为后来的访问提供的句柄
返回值：
SI_STATUS=SI_SUCCESSor
SI_DEVICE_NOT_FOUNDor
SI_INVALID_PARAMETERor
SI_GLOBAL_DATA_ERROR
2.4SI_Close
描述：
关闭一个通过SI_Open函数打开的设备句柄。
设置句柄的值为INVALID_HANDLE_VALUE;
支持的设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_Close（HANDLEHandle）
参数：
1Handle:
SI_Open函数返回的句柄
返回值：
SI_STATUS=SI_SUCCESSor
SI_INVALID_HANDLEor
SI_SYSTEM_ERROR_CODEor
SI_GLOBAL_DATA_ERROR
2.5SI_Read
描述:
从缓冲区中读取可用的字节并检索读取的字节数（可以小于要求的字节数）。
如果OVERLAPPED的对象为NULL，则同步返回（这个是默认的情况）但不会阻止系统执行。
如果OVERLAPPED对象初始化成功则立即返回。
如果读取完成则状态将变成SI_SUCCESS，如果I/O发生问题则返回STATUS_IO_PENDING。
如果返回的状态为STATUS_IO_PENDING,则OVERLAPPED对象可能使用WaitForSingleObject（）函数等待，检索数据或取消使用GetOverlappendResult（）和Cancello（）函数（微软MSDN上有记载）。
这个功能允许多个读取同时发生。
如果调用SI_Read函数数有任何可用数据，它都会返回，以便检查NumBytesReturned,以确定返回请求的数据。
为了确保SI_Read（）函数返回的字节数据正确，请使用SI_CheckRxQueue（）函数进行检查。
支持设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_Read（HANDLEHandle,LPVOIDBuffer,DWORDNumBytesToRead,DWORD*NumBytesReturned,OVERLAPPED*o=NULL）
参数：
1Handle:
SI_Open函数返回的设备句柄。
2Buffer：
存放读取数据的字符字节数组的地址。
3NumBytesToRead：
读取设备的数据缓冲区字节数（0-64KB）
4NumBytesReturned：
DWORD类型的变量地址，存放的是读入缓冲区的字节数
5（Optional）：
可用于异步读取的OVERLAPPED对象的地址
返回值：
SI_STATUS=SI_SUCCESSor
SI_READ_ERRORor
SI_INVALID_PARAMETERor
SI_INVALID_HANDLEor
SI_SI_READ_TIMED_OUTor
SI_IO_PENDINGor
SI_SYSTEM_ERROR_CODEor
SI_INVALID_REQUEST_LENGTHor
SI_DEVICE_IO_FAILED
2.6SI_Write
描述：
往设备的缓冲区写入特定的字节数。
如果异步对象OVERLAPPED设为NULL则这个函数同步写（默认设置）但不会阻止系统的执行。
就象SI_Read（）中描述的初始化OVERLAPPED对象一样。
支持设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_Write（HANDLEHandle,LPVOIDBuffer,DWORDNumBytesToWrite,DWORD*NumBytesWritten,OVERLAPPED*o=NULL）
参数：
1Handle：
SI_Open函数返回的句柄。
2Buffer：
要发送到设备的字节数组的地址。
3NumBytesToWrite：
写到设备中的字节数（0-4096bytes）
4NumBytesWritten：
实际写入到设备中的字节数组的地址（DWORD类型）
5（Optional）：
异步写的OVERLAPPED对象的地址。
返回值：
SI_STATUS=SI_SUCCESSor
SI_WRITE_ERRORor
SI_INVALID_REQUEST_LENGTHor
SI_INVALID_PARAMETERor
SI_INVALID_HANDLEor
SI_WRITE_TIMED_OUTor
SI_IO_PENDINGor
SI_SYSTEM_ERROR_CODEor
SI_DEVICE_IO_FAILED
2.7SI_FlushBuffers
描述：
在’F32x/F34x’设备上,这个函数刷新USBXpress设备的接收缓冲区与设备的发送缓冲区。
注：
使用’F32x/F34x’时参数2与3不起作用。
在CP210x设备上，参数2与3起作用。
如果参数2为非零值，CP210x设备的UART发送缓冲区被刷新；如果参数3为非零值，CP210x设备的UART接收缓冲区被刷新。
如果参数2和3都为非零值，则CP210x设备的UART接收与发送缓冲区都被刷新。
支持设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_FlushBuffers（HANDLEHandle,BYTEFlushTransmit,
BYTEFlushReceive）
参数：
1Handle:
SI_Open函数返回的设备名柄。
2FlushTransmit:
为非零值刷新CP210xUART的发送缓冲区。
3FlushReceive:
为非零值刷新设备的接收缓冲区。
返回值：
SI_STATUS=SI_SUCCESSor
SI_INVALID_HANDLEor
SI_SYSTEM_ERROR_CODE
2.8SI_SetTimeouts
描述：
设置读取与写入的超时时间。
超时间被用在SI_Read与SI_Write函数数中，当函数被同步调用时。
（异步函数OVERLAPPED被设为NULL的情况）。
默认的超时时间是INFINITE（0xFFFFFFFE）,但它可以被设置成0x0与0xFFFFFFFF之间的任意毫秒数。
支持的设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_SetTimeouts（DWORDReadTimeout,DWORDWriteTimeout）
参数：
1ReadTimeout:
SI_Read函数的超时时间（毫秒数）
2WriteTimeout：
SI_Write函数的超时时间（毫秒数）
返回值：
SI_STATUS=SI_SUCCESSor
SI_DEVICE_IO_FAILED
2.9SI_GetTimeouts
描述：
返回当前读取与写入的超时时间。
如果值为0xFFFFFFFF（INFINITE）则代表无限等待，否则超时时间为指定的毫秒数。
支持设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_GetTimeouts（LPDWORDReadTimeout,LPDWORDWriteTimeout）
1ReadTimeout:
SI_Read函数超时时间（毫秒数）
2WriteTimeOut:
SI_Write函数超时时间（毫秒数）
返回值：
SI_STATUS=SI_SUCCESSor
SI_INVALID_PARAMETERor
SI_DEVICE_IO_FAILED
2.10SI_CheckRXQueue
描述：
返回接收队列中的字节数和状态值，标明如果RX队列就绪（SI_QUEUE_READY）是否发生溢出（SI_QUEUE_OVERRUN）。
如果发生溢出，建议数据传输停止，使用SI_FlushBuffers命令刷新所有缓冲区。
支持设备：
C8051F320/1/6/7,C8051F340/1/2/3/4/5/6/7/8/9/A/B/C/D,
C8051F380/1/2/3/4/5/6/7,C8051T320/1/2/3/6/7,C8051T620/1/2/3,CP2101/2/3/4/5
原型：
SI_STATUSSI_CheckRXQueue（HANDLEHandle,LPDWORDNumBytesInQueue,
LPDWORDQueueStatus）
参数：
1Handle：
SI_Open返回的函数句柄。
2NumBytesInQueue:
DWORD类型的地址，是目前在返回的接收队列中包含的字节数
3QueueStatus：
DWORD类型的地址，是SI_RX_EMPTY（SI_RX_NO_OVERRUN）,SI_RX_OVERRUN,SI_RX_READY标志。
返回值：
SI_STATUS=SI_SUCCESSor
SI_DEVICE_IO_FAILEDor
SI_INVALID_HANDLEor
SI_INVALID_PARAMETER
2.11SI_SetBaudRate
描述：
设置波特率。
所支持的波特率列表请参阅设备数据手册。
支持的设备：
CP2101/2/3/4/5
原型：
SI_STATUSSI_SetBaudRate（HANDLEHandle,DWORDdwBaudRate）
参数：
1Handle：
SI_Open返回的设备句柄
2dwBaudRate:
DWORD类型的值，指定的波特率的值
返回值：
SI_STATUS=SI_SUCCESSor
SI_INVALID_BAUDRATEor
SI_INVALID_HANDLEor
SI_INVALID_PARAMETERor
SI_DEVICE_IO_FAILED
2.12SI_SetBaudDivisor
描述：
使用特定的分频值直接设置波特率
支持的设备：
CP2101/2/3/4/5
原型：
SI_STATUSSI_SetBaudDivisor（HANDLEHandle,WORDwBaudDivisor）
参数：
1Handle:
SI_Open返回的设备句柄。
2wBaudDivisor：
指定设置的波特率除数值。
返回值：
SI_STATUS=SI_SUCCESSor
SI_INVALID_HANDLEor
SI_INVALID_PARAMETERor
SI_DEVICE_IO_FAILED
2.13SI_SetLineControl
描述：
调整生产线控制设置:
字长停止校验位等。
请参考设备数据手册，进行有效的设置。
支持的设备：
CP2101/2/3/4/5
原型：
SI_STATUSSI_SetLineControl（HANDLEHandle,WORDwLineControl）
参数：
1Hanle：
SI_Open返回的句柄。
2wLineControl：
Word类型变量，所需的生产线控制设置。
可能输入的值如下：
Bits0-3NumberofStopbits
0:
1stopbit;
1:
1.5stopbits;
2:
2stopbits;
Bits4-7Parity
0:
None
1:
Odd
2:
Even
3:
Mark
4:
Space
Bits8-15Numberofbitsperword
5,6,7,or8
返回值：
SI_STATUS=SI_SUCCESSor
SI_DEVICE_IO_FAILEDor
SI_INVALID_HANDLEor
SI_INVALID_PARAMETER
2.14SI_SetFlowControl
描述：
调整以下的流量控制设置：
设置硬件握手，设置软件握手，调制解调器控制信号。
可以查看’SiUSBXp.h文件中的头定义’对引角进行定义。
支持设备：
CP2101/2/3/4/5
原型：
SI_STATUSSI_SetFlowControl（HANDLEHandle,BYTEbCTS_MaskCode,
BYTEbRTS_MaskCode,BYTEbDTR_MaskCode,BYTEbDSRMaskCode,
BYTEbDCD_MaskCode,BYTEbFlowXonXoff）
参数：
1Handle：
SI_Open返回的设备句柄。
2bCTS_MaskCode:
CTS引脚必须为如下值：
SI_STATUS_INPUT或者SI_HANDSHAKE_LINE
3bRTS_MaskCode：
RTS引脚的必须为如下值：
SI_HELD_ACTIVESI_HELD_INACTIVESI_FIRMWARE_CONTROLLEDSI_TRANSMIT_ACTIVE_SIGNAL
4bDTR_MaskCode:
DTR引脚的必须为下列值：
SI_HELD_INACTIVESI_HELD_ACTIVESI_FIRMWARE_CONTROLLED
5bDSR_MaskCode:
DSR引脚必须为如下值:
SI_STATUS_INPUTSI_HANDSHAKE_LINE
6bDCD_MaskCode:
DCD引脚必须为如下值:
SI_STATUS_INPUTSI_HANDSHAKE_LINE
7bFlowXonXoff:
值为0设置软件流控制为关闭状态，如果为非零值，使用指定的值。
返回值：
SI_STATUS=SI_SUCCESSor
SI_DEVICE_IO_FAILEDor
SI_INVALID_HANDLEor
SI_INVALID_PARAMETER
2.15SI_GetModemStatus
描述：
从设备获取调制解调器的状态。
包括调制解调器的引脚状态。
支持设备：
CP2101/2/3/4/5
原型：
SI_
升级会员 