Modules
	@ref SI_GetProductString() function flags

	RX Queue status flags

	Buffer size limits

	Input and Output pin Characteristics

	Mask and Latch value bit definitions

	@ref SI_GetPartNumber() returned PartNums (deprecated, see @ref silabs_defs.SILABS_PARTNUM_CPXXXX)

Data Structures
struct	PCOMM_STATUS

struct	_COMM_STATUS
	CP210x struct for reading from the device. Alias of this struct is COMM_STATUS. More...

Macros
#define	__declspec(n)
	__declspec(n) defination More...

#define	SI_USB_XP_API
	SI_USB_XP_API defination. More...

#define	WINAPI
	WINAPI defination. More...

Typedefs
typedef enum _SI_STATUS *	PSI_STATUS
	API Status return codes pointer. More...

typedef char	SI_DEVICE_STRING[256]
	Device string. More...

Enumerations
enum	SI_STATUS { SI_SUCCESS = SILABS_STATUS_SUCCESS, SI_INVALID_HANDLE = 0x01, SI_READ_ERROR = 0x02, SI_RX_QUEUE_NOT_READY = 0x03, SI_WRITE_ERROR = 0x04, SI_RESET_ERROR = 0x05, SI_INVALID_PARAMETER = 0x06, SI_INVALID_REQUEST_LENGTH = 0x07, SI_DEVICE_IO_FAILED = 0x08, SI_INVALID_BAUDRATE = 0x09, SI_FUNCTION_NOT_SUPPORTED = 0x0A, SI_GLOBAL_DATA_ERROR = 0x0B, SI_SYSTEM_ERROR_CODE = 0x0C, SI_READ_TIMED_OUT = 0x0D, SI_WRITE_TIMED_OUT = 0x0E, SI_IO_PENDING = 0x0F, SI_NOTHING_TO_CANCEL = 0xA0, SI_DEVICE_NOT_FOUND = 0xFF }

Functions
SI_STATUS	SI_GetNumDevices (LPDWORD lpdwNumDevices)
	Determines the number of CP210x devices configured as DirectAccess devices connected to the system. More...

SI_STATUS	SI_GetProductString (const DWORD dwDeviceIndex, LPVOID lpvDeviceString, const DWORD dwFlags)
	Gets a "Product string". More...

SI_STATUS	SI_GetProductStringSafe (const DWORD dwDeviceIndex, LPVOID lpvDeviceString, const size_t DeviceStringLenInBytes, const DWORD dwFlags)
	Gets a "Product string". More...

SI_STATUS	SI_Open (const DWORD DeviceIndex, PHANDLE pcyHandle)
	Opens a handle to the device. More...

SI_STATUS	SI_Close (const HANDLE cyHandle)
	Closes an open handle to the device. More...

SI_STATUS	SI_Read (const HANDLE cyHandle, LPVOID lpBuffer, const DWORD dwBytesToRead, LPDWORD lpdwBytesReturned, LPOVERLAPPED lpOverlapped=NULL)
	Read from the device. More...

SI_STATUS	SI_Write (const HANDLE cyHandle, LPVOID lpBuffer, const DWORD dwBytesToWrite, LPDWORD lpdwBytesWritten, LPOVERLAPPED lpOverlapped=NULL)
	Write buffer to device. More...

SI_STATUS	SI_DeviceIOControl (const HANDLE cyHandle, const DWORD dwIoControlCode, LPVOID lpInBuffer, const DWORD dwBytesToRead, LPVOID lpOutBuffer, const DWORD dwBytesToWrite, LPDWORD lpdwBytesSucceeded)
	Issue an I/O Control to the device. More...

SI_STATUS	SI_FlushBuffers (const HANDLE cyHandle, const BYTE FlushTransmit, const BYTE FlushReceive)
	Flush Buffers. More...

SI_STATUS	SI_SetTimeouts (const DWORD dwReadTimeoutInMilliseconds, const DWORD dwWriteTimeoutInMilliseconds)
	Set the Read- and Write-timeouts. More...

SI_STATUS	SI_GetTimeouts (LPDWORD lpdwReadTimeout, LPDWORD lpdwWriteTimeout)
	Reads and returns the Read- and Write-timeouts. More...

SI_STATUS	SI_CheckRXQueue (const HANDLE cyHandle, LPDWORD lpdwNumBytesInQueue, LPDWORD lpdwQueueStatus)
	Retrieve receive queue status. More...

SI_STATUS	SI_SetBaudRate (const HANDLE cyHandle, const DWORD dwBaudRate)
	Set the baudrate on the device. More...

SI_STATUS	SI_SetBaudDivisor (const HANDLE cyHandle, const WORD wBaudDivisor)
	Set the baudrate on the device using a divisor. More...

SI_STATUS	SI_SetLineControl (const HANDLE cyHandle, const WORD wLineControl)
	Set the line control settings. More...

SI_STATUS	SI_SetFlowControl (const HANDLE cyHandle, const BYTE bCTS_MaskCode, const BYTE bRTS_MaskCode, const BYTE bDTR_MaskCode, const BYTE bDSR_MaskCode, const BYTE bDCD_MaskCode, const BOOL bFlowXonXoff)
	Set the flow control settings. More...

SI_STATUS	SI_GetModemStatus (const HANDLE cyHandle, PBYTE pModemStatus)
	Get the Modem Status from the device, including the modem pin states. More...

SI_STATUS	SI_GetCommStatus (const HANDLE cyHandle, PCOMM_STATUS pCommStatus)
	Get the Comm Status from the device. More...

SI_STATUS	SI_SetBreak (const HANDLE cyHandle, const WORD wBreakState)
	Send a break state to the device. More...

SI_STATUS	SI_ReadLatch (const HANDLE cyHandle, LPWORD lpwLatch)
	Reads and returns the current port latch value from the device. More...

SI_STATUS	SI_WriteLatch (const HANDLE cyHandle, const WORD mask, const WORD latch)
	Writes a new port latch value to the device. More...

SI_STATUS	SI_GetPartNumber (const HANDLE cyHandle, LPBYTE lpbPartNum)
	Reads and returns the Part Number from the device. More...

SI_STATUS	SI_GetPartLibraryVersion (const HANDLE cyHandle, BYTE pLibraryVersion[2])
	Reads and returns the firmware library version from the device. More...

SI_STATUS	SI_GetInterfaceNumber (const HANDLE cyHandle, LPBYTE lpbInterfaceNum)
	Get Interface Number. More...

SI_STATUS	SI_GetDeviceProductString (const HANDLE cyHandle, LPVOID lpProductString, LPBYTE lpbProductStringLengthInBytes, const BOOL bConvertToASCII=TRUE)
	Reads and returns the Product string directly from the device. More...

SI_STATUS	SI_GetDLLVersion (DWORD HighVersion, DWORD LowVersion)
	Reads and returns the DLL library version from the DLL. More...

SI_STATUS	SI_GetDriverVersion (DWORD HighVersion, DWORD LowVersion)
	Reads and returns the kernel-mode driver version from the driver (deprecated (architecture no longer uses a kernel-mode driver)) More...

SI_STATUS	SI_CancelIo (const HANDLE cyHandle)
	Cancels any pending IO on a device opened with an OVERLAPPED object. More...

SI_STATUS	SI_CancelIoEx (const HANDLE cyHandle, LPOVERLAPPED lpOverlapped)
	Cancels particular pending IO on a device opened with an OVERLAPPED object. More...

Detailed Description

This document supercedes, obsoletes and takes precedences over AN169.

The CP210x DirectAccess Host API provides access to the GPIO port latch, and the DLL is meant for distribution with the product containing a CP210x DirectAccess device. Please provide feedback to Silicon Labs if you require the static-linked (I.e. linked at build time) verison of this device interface library.

The CP210x DirectAccess Host API is provided in the form of a Windows Dynamic Link Library (DLL), siusbxp.DLL and as a Windows static link library (.static.LIB). The host interface DLL communicates with the bridge controller device via the operating system's USB stack.

Custom applications can use the CP210x DirectAccess API implemented in siusbxp.DLL. To use functions implemented in siusbxp.DLL link siusbxp.LIB include SiUSBXp.h into any source code files that call any functions implemented in siusbxp.DLL and include the PATH to the location of siusbxp.DLL in your custom application Visual Studio .VCXPROJ Profile File's Properties->Linker->General->Additional Library Directories property.

Typically, the user initiates communication with the target CP210x DirectAccess device by making a call to SI_GetNumDevices(). This call returns the number of DirectAccess CP210x target devices. A handle to the device must first be opened by a call to SI_Open() using an index determined from the call to SI_GetNumDevices(). The handle will be used for all subsequent accesses.

Data I/O is performed using the SI_Write() and SI_Read() functions.

Additional functions are provided to flush the transmit and receive buffers (SI_FlushBuffers()), set receive and transmit timeouts(SI_SetTimeouts()), check the receive buffer's status (SI_CheckRXQueue()), and miscellaneous device control(SI_DeviceIOControl()).

When I/O operations are complete, the device handle is closed by a call to SI_Close().

Functions are available to set the baud rate (SI_SetBaudRate()); set the baud divisor (SI_SetBaudDivisor()); adjust the line control settings such as word length, stop bits, and parity (SI_SetLineControl()); set hardware handshaking, software handshaking, and modem control signals (SI_SetFlowControl()); and get modem status (SI_GetModemStatus()). Additional functions are available for some CP210x devices to get (SI_ReadLatch()) and set (SI_WriteLatch()) the values of the additional GPIO pins available on the device. In order to differentiate between CP210x DirectAccess devices, a function (SI_GetPartNumber()) has been provided to return the part number.

Data Structure Documentation

◆ COMM_STATUS

struct COMM_STATUS

Data Fields
UCHAR	bEofReceived
UCHAR	bReserved
UCHAR	bWaitForImmediate
ULONG	ulAmountInInQueue
ULONG	ulAmountInOutQueue
ULONG	ulErrors
ULONG	ulHoldReasons

◆ _COMM_STATUS

struct _COMM_STATUS

CP210x struct for reading from the device. Alias of this struct is COMM_STATUS.

Same as SERIAL_STATUS in ntddser.h plus one byte The h/w doc says it's 0x0013 bytes

Macro Definition Documentation

◆ __declspec

#define __declspec ( n )

__declspec(n) defination

◆ SI_USB_XP_API

#define SI_USB_XP_API

SI_USB_XP_API defination.

◆ WINAPI

#define WINAPI

WINAPI defination.

Typedef Documentation

◆ PSI_STATUS

PSI_STATUS

API Status return codes pointer.

◆ SI_DEVICE_STRING

SI_DEVICE_STRING

Device string.

Enumeration Type Documentation

◆ SI_STATUS

enum SI_STATUS

Enumerator
SI_SUCCESS	SILABS_STATUS no error
SI_INVALID_HANDLE	an handle parameter was not valid
SI_READ_ERROR	Read error.
SI_RX_QUEUE_NOT_READY	Receive Queue NOT ready.
SI_WRITE_ERROR	Write error.
SI_RESET_ERROR	Reset error.
SI_INVALID_PARAMETER	a parameter was not valid
SI_INVALID_REQUEST_LENGTH	Invalid Request Length.
SI_DEVICE_IO_FAILED	device I/O failed
SI_INVALID_BAUDRATE	INvalid baudrate.
SI_FUNCTION_NOT_SUPPORTED	the specified function is not supported
SI_GLOBAL_DATA_ERROR	global data error
SI_SYSTEM_ERROR_CODE	an unexpected, unrecoverable error happened while interacting with the operating system
SI_READ_TIMED_OUT	Read timed out.
SI_WRITE_TIMED_OUT	Write timed out.
SI_IO_PENDING	I/O pending.
SI_NOTHING_TO_CANCEL	Nothing to cancel.
SI_DEVICE_NOT_FOUND	the specified device was not found

Function Documentation

◆ SI_CancelIo()

SI_STATUS SI_CancelIo ( const HANDLE cyHandle )

Cancels any pending IO on a device opened with an OVERLAPPED object.

Parameters

[in] cyHandle is an open handle to the device as returned by SI_Open()

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success, something was cancelled
SI_INVALID_HANDLE	– cyHandle is invalid
SI_NOTHING_TO_CANCEL	– success, there was nothing to cancel
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?

◆ SI_CancelIoEx()

SI_STATUS SI_CancelIoEx	(	const HANDLE	cyHandle,
		LPOVERLAPPED	lpOverlapped
	)

Cancels particular pending IO on a device opened with an OVERLAPPED object.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	lpOverlapped	is a pointer to an Windows OVERLAPPED object associated with an asynchronous SI_Read() or SI_Write().

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success, something was cancelled
SI_INVALID_HANDLE	– cyHandle is invalid
SI_NOTHING_TO_CANCEL	– success, there was nothing to cancel
SI_INVALID_PARAMETER	– lpOverlapped is an unexpected value

◆ SI_CheckRXQueue()

SI_STATUS SI_CheckRXQueue	(	const HANDLE	cyHandle,
		LPDWORD	lpdwNumBytesInQueue,
		LPDWORD	lpdwQueueStatus
	)

Retrieve receive queue status.

Returns the number of bytes in the receive queue and a status value that indicates if an overrun (SI_QUEUE_OVERRUN) has occurred and if the RX queue is ready (SI_QUEUE_READY) for reading. Upon indication of an Overrun condition it is recommended that data transfer be stopped and all buffers be flushed using the SI_FlushBuffers() command.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	lpdwNumBytesInQueue	points at a 4-byte buffer into which the number of bytes currently in the receive queue will be written
[out]	lpdwQueueStatus	points at a 4-byte buffer into which the SI_RX_EMPTY, SI_RX_NO_OVERRUN, SI_RX_OVERRUN, or SI_RX_READY flag will be written as a bit mask

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– lpdwNumBytesInQueue or lpdwQueueStatus is an unexpected value
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_Close()

SI_STATUS SI_Close ( const HANDLE cyHandle )

Closes an open handle to the device.

Parameters

[in] cyHandle is an open handle to the device as returned by SI_Open()

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?

◆ SI_DeviceIOControl()

SI_STATUS SI_DeviceIOControl	(	const HANDLE	cyHandle,
		const DWORD	dwIoControlCode,
		LPVOID	lpInBuffer,
		const DWORD	dwBytesToRead,
		LPVOID	lpOutBuffer,
		const DWORD	dwBytesToWrite,
		LPDWORD	lpdwBytesSucceeded
	)

Issue an I/O Control to the device.

Interface for any miscellaneous device control functions. A separate call to SI_DeviceIOControl() is required for each input or output operation. A single call cannot be used to perform both an input and output operation simultaneously. Refer to DeviceIOControl function definition on MSDN Help for more details.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	dwIoControlCode	is the Code to select control function
[in]	lpInBuffer	Pointer to input data buffer
[in]	dwBytesToRead	Number of bytes to be read into InBuffer
[out]	lpOutBuffer	Pointer to output data buffer.
[in]	dwBytesToWrite	Number of bytes to write from OutBuffer
[out]	lpdwBytesSucceeded	Address of a DWORD variable that will contain the number of bytes read by a input operation or the number of bytes written by a output operation on return.

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– dwIoControlCode, lpInBuffer, dwBytesToRead, lpOutBuffer, dwBytesToWrite or lpdwBytesSucceeded is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ SI_FlushBuffers()

SI_STATUS SI_FlushBuffers	(	const HANDLE	cyHandle,
		const BYTE	FlushTransmit,
		const BYTE	FlushReceive
	)

Flush Buffers.

Flushes both the receive buffer and/or the transmit buffer in the device. Note: Parameter 2 and 3 have no effect and any value can be passed when used with USB MCU devices. If FlushTransmit is non-zero, the CP210x device’s UART transmit buffer is flushed. If FlushReceive is non-zero, the CP210x device’s UART receive buffer is flushed. If both FlushTransmit and FlushReceive are non-zero, then both the CP210x device UART transmit buffer and UART receive buffer are flushed.

Note: flushed means purged, discarded.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	FlushTransmit	if non-zero, the device’s UART transmit buffer is flushed/purged.
[in]	FlushReceive	if non-zero, the device’s UART receive buffer is flushed/purged.

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_GetCommStatus()

SI_STATUS SI_GetCommStatus	(	const HANDLE	cyHandle,
		PCOMM_STATUS	pCommStatus
	)

Get the Comm Status from the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	pCommStatus	points at a 1-byte buffer into which the Comm Status will be written

Where the current states of the RS-232 modem control lines are defined as: Bit 0: DTR State Bit 1 : RTS State Bit 4 : CTS State Bit 5 : DSR State Bit 6 : RI State Bit 7 : DCD State

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– pCommStatus is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_GetDeviceProductString()

SI_STATUS SI_GetDeviceProductString	(	const HANDLE	cyHandle,
		LPVOID	lpProductString,
		LPBYTE	lpbProductStringLengthInBytes,
		const BOOL	bConvertToASCII = `TRUE`
	)

Reads and returns the Product string directly from the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	lpProductString	points at a buffer into which the Product string will be written
[out]	lpbProductStringLengthInBytes	points at a 1-byte buffer into which the total number of bytes in the returned Product string is returned.
[in]	bConvertToASCII	is a true or false value indicating whether the Product string is an 16-bit UCS-2 character string needing converting to 8-bit ascii characters (true) or not (false).

lpProductString will typically be an address of a string of type SI_DEVICE_STRING or a similarly sized string of at least SI_MAX_DEVICE_STRLEN characters. The returned Product string is "as is" retrieved from the device (other than converted to ascii if bConvertToASCII is true). Specifically, it may not be NULL terminated.

Note: Length of lpProductString must be <= SI_MAX_DEVICE_STRLEN; BUG: This is an string-UNSAFE function, not defensize against a "too small" buffer provided as the lpProductString parameter.

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– lpProduct or lpbLength is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ SI_GetDLLVersion()

SI_STATUS SI_GetDLLVersion	(	DWORD *	HighVersion,
		DWORD *	LowVersion
	)

Reads and returns the DLL library version from the DLL.

Parameters

[out]	HighVersion	points at a 4-byte-sized buffer into which the high-byte of the DLL Version value will be written
[out]	LowVersion	points at a 4-byte-sized buffer into which the low-byte of the DLL Version value will be written

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_PARAMETER	– HighVersion or LowVersion is an unexpected value

◆ SI_GetDriverVersion()

SI_STATUS SI_GetDriverVersion	(	DWORD *	HighVersion,
		DWORD *	LowVersion
	)

Reads and returns the kernel-mode driver version from the driver (deprecated (architecture no longer uses a kernel-mode driver))

Parameters

[out]	HighVersion	points at a byte-sized buffer into which the high-byte of the Driver Version value will be written
[out]	LowVersion	points at a byte-sized buffer into which the low-byte of the Driver Version value will be written

Returns: Always returns SI_FUNCTION_NOT_SUPPORTED, this function has been deprecated.

◆ SI_GetInterfaceNumber()

SI_STATUS SI_GetInterfaceNumber	(	const HANDLE	cyHandle,
		LPBYTE	lpbInterfaceNum
	)

Get Interface Number.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	lpbInterfaceNum	points at a 1-byte buffer into which the Interface Number will be written

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– lpbInterfaceNum is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_GetModemStatus()

SI_STATUS SI_GetModemStatus	(	const HANDLE	cyHandle,
		PBYTE	pModemStatus
	)

Get the Modem Status from the device, including the modem pin states.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	pModemStatus	points at a 1-byte buffer into which the Modem Status will be written

Where the current states of the RS-232 modem control lines are defined as: Bit 0: DTR State Bit 1 : RTS State Bit 4 : CTS State Bit 5 : DSR State Bit 6 : RI State Bit 7 : DCD State

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– pModemStatus is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_GetNumDevices()

SI_STATUS SI_GetNumDevices ( LPDWORD lpdwNumDevices )

Determines the number of CP210x devices configured as DirectAccess devices connected to the system.

Parameters

[out] lpdwNumDevices a pointer to a DWORD/4-byte location to hold the returned device count

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_PARAMETER	– lpdwNumDevices is an unexpected value

◆ SI_GetPartLibraryVersion()

SI_STATUS SI_GetPartLibraryVersion	(	const HANDLE	cyHandle,
		BYTE	pLibraryVersion[2]
	)

Reads and returns the firmware library version from the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	pLibraryVersion	points at a 2-byte buffer into which the Firmware Library Version value will be written

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– pLibraryVersion is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_GetPartNumber()

SI_STATUS SI_GetPartNumber	(	const HANDLE	cyHandle,
		LPBYTE	lpbPartNum
	)

Reads and returns the Part Number from the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	lpbPartNum	points at a 1-byte buffer into which the SILABS_PARTNUM_CPXXXX Part Number value will be written

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– lpbPartNum is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_GetProductString()

SI_STATUS SI_GetProductString	(	const DWORD	dwDeviceIndex,
		LPVOID	lpvDeviceString,
		const DWORD	dwFlags
	)

Gets a "Product string".

This function returns a NULL-terminated serial number string, product description string, or full path string for the device specified by an index passed in the dwDeviceIndex parameter. The index of the first device is 0, and the index of the last device is the value(NumDevices) returned by SI_GetNumDevices() - 1.

The full path string is the "device interface path" or "Device Path". This path can be passed to Win32 functions such as CreateFile().

The Serial Number string is derived from the "full path" string.

The Description string is either the "description of a device" Plug and Play device property from the Registry, if available, else the "friendly name of a device" Plug and Play device property from the Registry, if available, else the same "device interface path" returned for the "full path" string.

The VID string is derived from the "full path" string.

The PID string is derived from the "full path" string.

Returned strings are NULL-terminated.

Note: : This function may return cached data, or data from the device driver. To access the data from the device directly, use SI_GetDeviceProductString().; Length of lpvDeviceString must be <= SI_MAX_DEVICE_STRLEN; BUG: This is an string-UNSAFE function, not defensize against a "too small" buffer provided as the lpvDeviceString parameter.; Deprecated. Use SI_GetProductStringSafe() instead

Parameters

[in]	dwDeviceIndex	is the desired device's index into the device list used to determine SI_GetNumDevices()
[out]	lpvDeviceString	points at a buffer into which the "Product string" will be copied and returned
[in]	dwFlags	is the indication of which Product string to return, see SI_GetProductString() function flags

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_PARAMETER	– lpvDeviceString or dwFlags is an unexpected value
SI_DEVICE_NOT_FOUND	– the device specified by the dwDeviceIndex was not found
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ SI_GetProductStringSafe()

SI_STATUS SI_GetProductStringSafe	(	const DWORD	dwDeviceIndex,
		LPVOID	lpvDeviceString,
		const size_t	DeviceStringLenInBytes,
		const DWORD	dwFlags
	)

Gets a "Product string".

This function returns a NULL-terminated serial number string, product description string, or full path string for the device specified by an index passed in the dwDeviceIndex parameter. The index of the first device is 0, and the index of the last device is the value(NumDevices) returned by SI_GetNumDevices() - 1.

The full path string is the "device interface path" or "Device Path". This path can be passed to Win32 functions such as CreateFile().

The Serial Number string is derived from the "full path" string.

The Description string is either the "description of a device" Plug and Play device property from the Registry, if available, else the "friendly name of a device" Plug and Play device property from the Registry, if available, else the same "device interface path" returned for the "full path" string.

The VID string is derived from the "full path" string.

The PID string is derived from the "full path" string.

Returned strings are NULL-terminated.

Note: : This function may return cached data, or data from the device driver. To access the data from the device directly, use SI_GetDeviceProductString().; Length of lpvDeviceString must be <= SI_MAX_DEVICE_STRLEN; BUG: This is an string-UNSAFE function, not defensize against a "too small" buffer provided as the lpvDeviceString parameter.; Deprecated. Use SI_GetProductStringSafe() instead

Parameters

[in]	dwDeviceIndex	is the desired device's index into the device list used to determine SI_GetNumDevices()
[out]	lpvDeviceString	points at a buffer into which the "Product string" will be copied and returned
[in]	DeviceStringLenInBytes	the length in bytes of lpvDeviceString the buffer into which the Product String will be copied and returned
[in]	dwFlags	is the indication of which Product string to return, see SI_GetProductString() function flags

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_PARAMETER	– lpvDeviceString or dwFlags is an unexpected value
SI_DEVICE_NOT_FOUND	– the device specified by the dwDeviceIndex was not found
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ SI_GetTimeouts()

SI_STATUS SI_GetTimeouts	(	LPDWORD	lpdwReadTimeout,
		LPDWORD	lpdwWriteTimeout
	)

Reads and returns the Read- and Write-timeouts.

Returns the current read and write timeouts. If a timeout value is 0xFFFFFFFF (INFINITE) it has been set to wait infinitely; otherwise the timeouts are specified in milliseconds.

Parameters

[out]	lpdwReadTimeout	points at a 4-byte buffer into which the read timeout value in milliseconds will be written
[out]	lpdwWriteTimeout	points at a 4-byte buffer into which the write timeout value in milliseconds will be written

Note: a value of ~0 (0xFFFFFFFF) means an infinite-timeout

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_PARAMETER	– lpdwReadTimeout or lpdwWriteTimeout is an unexpected value
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?

◆ SI_Open()

SI_STATUS SI_Open	(	const DWORD	DeviceIndex,
		PHANDLE	pcyHandle
	)

Opens a handle to the device.

Opens and returns a handle to a device using a device index determined by the number returned from SI_GetNumDevices().

Close by passing the returned handle to SI_Close()

Parameters

[in]	DeviceIndex	is the desired device's zero-based index into the device list used to determine SI_GetNumDevices(). 0 for the first device, 1 for the second, etc.
[out]	pcyHandle	is a pointer to a HANDLE/4-byte location to hold the returned open handle to the device

The returned handle is used for all/most subsequent accesses to the device (I.e. the cyHandle parameter to all/most other API functions)

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_PARAMETER	– pcyHandle or dwFlags is an unexpected value
SI_DEVICE_NOT_FOUND	– the device specified by the dwDeviceIndex was not found
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?

◆ SI_Read()

SI_STATUS SI_Read	(	const HANDLE	cyHandle,
		LPVOID	lpBuffer,
		const DWORD	dwBytesToRead,
		LPDWORD	lpdwBytesReturned,
		LPOVERLAPPED	lpOverlapped = `NULL`
	)

Read from the device.

Reads the available number of bytes into the supplied buffer and retrieves the number of bytes that were read (this can be less than the number of bytes requested). This function returns synchronously if the overlapped object is set to NULL (this happens by default) but will not block system execution. If an initialized OVERLAPPED object is passed then the function returns immediately. If the read completed then the status will be SI_SUCCESS but if I/O is still pending then it will return SI_IO_PENDING. If SI_IO_PENDING is returned, the OVERLAPPED object can then be waited on using WaitForSingleObject(), and retrieve data or cancel using GetOverlappedResult() (as documented on MSDN by Microsoft) or SI_CancelIo() respectively. This functionality allows for multiple reads to be issued and waited on at a time. If any data is available when SI_Read() is called it will return so check lpdwBytesReturned to determine if all requested data was returned. To make sure that SI_Read() returns the requested number of bytes use SI_CheckRXQueue().

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	lpBuffer	is a pointer to a buffer into which the read data will be written and returned
[in]	dwBytesToRead	is the requested number of bytes to be read
[out]	lpdwBytesReturned	is a pointer to a 4-byte buffer into which the actual number of bytes read and placed into the buffer will be written and returned (the number of bytes actually read can be less than the number of bytes requested).
[in]	lpOverlapped	is optional and if provided is a pointer to an Windows OVERLAPPED object that can be used for asynchronous reads.

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– lpBuffer, dwBytesToRead, lpdwBytesReturned or lpOverlapped is an unexpected value
SI_IO_PENDING	– the optional lpOverlapped overlapped mechanism was utilized and the read was not completed immediately
SI_READ_ERROR	– TBD
SI_READ_TIMED_OUT	– TBD
SI_INVALID_REQUEST_LENGTH	– TBD
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_ReadLatch()

SI_STATUS SI_ReadLatch	(	const HANDLE	cyHandle,
		LPWORD	lpwLatch
	)

Reads and returns the current port latch value from the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[out]	lpwLatch	points at a 2-byte buffer into which the port latch value will be written

GPIO latch value is Logic High = 1, Logic Low = 0.

Note: Supported on CP210x devices IsWriteReadLatchPartNum()

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_FUNCTION_NOT_SUPPORTED	– the device does not support port latch
SI_INVALID_PARAMETER	– lpwLatch is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_SetBaudDivisor()

SI_STATUS SI_SetBaudDivisor	(	const HANDLE	cyHandle,
		const WORD	wBaudDivisor
	)

Set the baudrate on the device using a divisor.

Sets the Baud Rate directly by using a specific divisor value.

Note: Deprecated. Use SI_SetBaudRate() instead

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	wBaudDivisor	is the Baud Devisor to use on the device

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_SetBaudRate()

SI_STATUS SI_SetBaudRate	(	const HANDLE	cyHandle,
		const DWORD	dwBaudRate
	)

Set the baudrate on the device.

Note: Refer to the device data sheet for a list of Baud Rates supported by the device. TBD insert URL of data sheets.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	dwBaudRate	is the Baud Rate to set on the device

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_BAUDRATE	– dwBaudRate is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_SetBreak()

SI_STATUS SI_SetBreak	(	const HANDLE	cyHandle,
		const WORD	wBreakState
	)

Send a break state to the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	wBreakState	is the break state to set.

If wBreakState is a 0x0000 then the break is reset. If this value is a 0x0001 then a break is transmitted.

Note: that this function is not necessarily synchronized with queued transmit data.

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– wBreakState is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_SetFlowControl()

SI_STATUS SI_SetFlowControl	(	const HANDLE	cyHandle,
		const BYTE	bCTS_MaskCode,
		const BYTE	bRTS_MaskCode,
		const BYTE	bDTR_MaskCode,
		const BYTE	bDSR_MaskCode,
		const BYTE	bDCD_MaskCode,
		const BOOL	bFlowXonXoff
	)

Set the flow control settings.

Adjusts the following flow control settings: set hardware handshaking, software handshaking, and modem control signals.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	bCTS_MaskCode	— The CTS pin characteristic
[in]	bRTS_MaskCode	— The RTS pin characteristic
[in]	bDTR_MaskCode	— The DTR pin characteristic
[in]	bDSR_MaskCode	— The DSR pin characteristic
[in]	bDCD_MaskCode	— The DCD pin characteristic
[in]	bFlowXonXoff	— Sets software flow control to be off IFF the value is 0, and on using the character value specified IFF value is non-zero (TBD what character specified where?)

Where: bCTS_MaskCode — The CTS pin characteristic must be as follows: SI_STATUS_INPUT or SI_HANDSHAKE_LINE. bRTS_MaskCode—The RTS pin characteristic must be as follows : SI_HELD_ACTIVE, SI_HELD_INACTIVE, SI_FIRMWARE_CONTROLLED or SI_TRANSMIT_ACTIVE_SIGNAL. bDTR_MaskCode—The DTR pin characteristic must be as follows : SI_HELD_INACTIVE, SI_HELD_ACTIVE or SI_FIRMWARE_CONTROLLED. bDSR_MaskCode—The DSR pin characteristic must be as follows : SI_STATUS_INPUT or SI_HANDSHAKE_LINE. bDCD_MaskCode—The DCD pin characteristic must be as follows : SI_STATUS_INPUT or SI_HANDSHAKE_LINE.

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– bCTS_MaskCode, bRTS_MaskCode, bDTR_MaskCode, bDSR_MaskCode, bDCD_MaskCode or bFlowXonXoff is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_SetLineControl()

SI_STATUS SI_SetLineControl	(	const HANDLE	cyHandle,
		const WORD	wLineControl
	)

Set the line control settings.

Adjusts the line control settings: word length, stop bits, and parity. Refer to the device data sheet for valid line control settings. TBD insert URL of data sheets.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	wLineControl	is a 16-bit encoding of the desired line control settings to use on the device

wLineControl encoding is as follows: settings are as follows : Bits 0–3 Number of Stop bits 0 : 1 stop bit; 1: 1.5 stop bits; 2: 2 stop bits Bits 4–7 Parity 0 : None 1 : Odd 2 : Even 3 : Mark 4 : Space Bits 8–15 Number of bits per word 5, 6, 7, or 8

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– wLineControl is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_SetTimeouts()

SI_STATUS SI_SetTimeouts	(	const DWORD	dwReadTimeoutInMilliseconds,
		const DWORD	dwWriteTimeoutInMilliseconds
	)

Set the Read- and Write-timeouts.

Sets the read and write timeouts. Timeouts are used for SI_Read() and SI_Write() when called synchronously (OVERLAPPED* lpOverlapped is set to NULL). The default value for timeouts is INFINITE (0xFFFFFFFF), but they can be set to wait for any number of milliseconds between 0x0 and 0xFFFFFFFE.

Parameters

[in]	dwReadTimeoutInMilliseconds	is the read timeout in milliseconds
[in]	dwWriteTimeoutInMilliseconds	is the write timeout in milliseconds

Note: a value of ~0 (0xFFFFFFFF) means an infinite-timeout

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?

◆ SI_Write()

SI_STATUS SI_Write	(	const HANDLE	cyHandle,
		LPVOID	lpBuffer,
		const DWORD	dwBytesToWrite,
		LPDWORD	lpdwBytesWritten,
		LPOVERLAPPED	lpOverlapped = `NULL`
	)

Write buffer to device.

Writes the specified number of bytes from the supplied buffer to the device. This function returns synchronously if the overlapped object is set to NULL (this happens by default) but will not block system execution. An initialized OVERLAPPED object may be specified and waited on just as described in the description for SI_Read().

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	lpBuffer	points at a buffer containing the data to be written to the device
[in]	dwBytesToWrite	is the number of bytes in that buffer to be written to the device
[out]	lpdwBytesWritten	is a pointer to a 4-byte buffer into which the actual number of bytes written to the device will be written and returned (the number of bytes actually written can be less than the number of bytes requested).
[in]	lpOverlapped	is optional and if provided is a pointer to an Windows OVERLAPPED object that can be used for asynchronous writes.

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_INVALID_PARAMETER	– lpBuffer, dwBytesToWrite, lpdwBytesWritten or lpOverlapped is an unexpected value
SI_IO_PENDING	– the optional lpOverlapped overlapped mechanism was utilized and the read was not completed immediately
SI_WRITE_ERROR	– TBD
SI_WRITE_TIMED_OUT	– TBD
SI_INVALID_REQUEST_LENGTH	– TBD
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

◆ SI_WriteLatch()

SI_STATUS SI_WriteLatch	(	const HANDLE	cyHandle,
		const WORD	mask,
		const WORD	latch
	)

Writes a new port latch value to the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by SI_Open()
[in]	mask	is a bit-mask which determines which pins of `latch` to change [Change = 1, Do not change = 0].
[in]	latch	is the new 2-byte GPIO port latch value to be written to the device

Note: Supported on CP210x devices IsWriteReadLatchPartNum()

Returns: Returns SI_SUCCESS on success, or another SI_STATUS Return value if there is an error.

Return values

SI_SUCCESS	– success
SI_INVALID_HANDLE	– cyHandle is invalid
SI_FUNCTION_NOT_SUPPORTED	– the device does not support port latch
SI_INVALID_PARAMETER	– `mask` and/or `latch` is an unexpected value
SI_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner
SI_GLOBAL_DATA_ERROR	– driver globals could not be found. Internal OS error?
SI_SYSTEM_ERROR_CODE	– a device context could not be determined for the device. Internal OS error?

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ COMM_STATUS

◆ _COMM_STATUS

Macro Definition Documentation

◆ __declspec

◆ SI_USB_XP_API

◆ WINAPI

Typedef Documentation

◆ PSI_STATUS

◆ SI_DEVICE_STRING

Enumeration Type Documentation

◆ SI_STATUS

Function Documentation

◆ SI_CancelIo()

◆ SI_CancelIoEx()

◆ SI_CheckRXQueue()

◆ SI_Close()

◆ SI_DeviceIOControl()

◆ SI_FlushBuffers()

◆ SI_GetCommStatus()

◆ SI_GetDeviceProductString()

◆ SI_GetDLLVersion()

◆ SI_GetDriverVersion()

◆ SI_GetInterfaceNumber()

◆ SI_GetModemStatus()

◆ SI_GetNumDevices()

◆ SI_GetPartLibraryVersion()

◆ SI_GetPartNumber()

◆ SI_GetProductString()

◆ SI_GetProductStringSafe()

◆ SI_GetTimeouts()

◆ SI_Open()

◆ SI_Read()

◆ SI_ReadLatch()

◆ SI_SetBaudDivisor()

◆ SI_SetBaudRate()

◆ SI_SetBreak()

◆ SI_SetFlowControl()

◆ SI_SetLineControl()

◆ SI_SetTimeouts()

◆ SI_Write()

◆ SI_WriteLatch()