Modules
	Deprecated Confused Version Part Numbers

	CP210x Status Codes - runtime
	API Status return codes.

	GPIO Mask and Latch value bit definitions

Macros
#define	CP210xDLL_API
	CP210xDLL_API defination. More...

#define	WINAPI
	WINAPI defination. More...

#define	CP210xRUNTIMEDLL_API
	CP210xRUNTIMEDLL_API defination. More...

#define	CP210x_MAX_PRODUCT_STRLEN 126
	Max Product string length. More...

#define	CP210x_MAX_SERIAL_STRLEN_S 126
	Max Serial Number string length. More...

#define	CP210x_MAX_SETUP_STRING_SIZE 246
	Max setup string size. More...

Typedefs
typedef char	CP210x_PRODUCT_STRING[126]
	cp210x product string More...

typedef char	CP210x_SERIAL_STRING_S[126]
	cp210x serial string More...

Functions
CP210x_STATUS	CP210xRT_GetNumDevices (uint32_t *lpdwNumDevices)
	Determines the number of CP210x devices connected to the system. More...

CP210x_STATUS	CP210xRT_Open (const uint32_t DeviceIndex, PHANDLE pcyHandle)
	Opens a handle to the device. More...

CP210x_STATUS	CP210xRT_Close (const HANDLE cyHandle)
	Closes an open handle to the device. More...

CP210x_STATUS	CP210xRT_ReadLatch (const HANDLE cyHandle, LPWORD lpwLatch)

CP210x_STATUS	CP210xRT_WriteLatch (const HANDLE cyHandle, const WORD mask, const WORD latch)
	Sets a new current GPIO port latch value for the device. More...

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

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

CP210x_STATUS	CP210xRT_GetDeviceSerialNumber (const HANDLE cyHandle, LPVOID lpSerialNumberString, LPBYTE lpbSerialNumberStringLengthInBytes, const BOOL bConvertToASCII=TRUE)
	Reads and returns the Serial Number String directly from the device. More...

CP210x_STATUS	CP210xRT_GetDeviceInterfaceString (const HANDLE cyHandle, LPVOID lpInterfaceString, LPBYTE lpbInterfaceStringLengthInBytes, const BOOL bConvertToASCII)
	Reads and returns the Interface String directly from the device. More...

CP210x_STATUS	CP210xRT_GetReceiverMaxTimeout (const HANDLE cyHandle, uint16_t *pReceiverMaxTimeoutInMicroseconds)
	Reads and returns the Receiver Max Timeout directly from the device. More...

CP210x_STATUS	CP210xRT_SetReceiverMaxTimeout (const HANDLE cyHandle, const uint16_t ReceiverMaxTimeoutInMicroseconds)
	Sets the Receiver Max Timeout directly to the device. More...

Detailed Description

The Silicon Labs CP210x USB-to-UART bridges are devices that communicate over the Universal Serial Bus(USB) to perform Universal Asynchronous Receiver / Transmitter (UART) data transfers. These devices have many programmable options that can be configured via USB. These devices also often include flexible GPIO functions that can be configured and accessed via USB during runtime. Silicon Labs provides libraries that can be used to configure these devices and access their GPIOs.

Two interface library files can be used to interface with CP210x devices, CP210xManufacturing.DLL and .LIB, which is responsible for reading and writing the device settings, and CP210xRuntime.DLL and .LIB, which is responsible for interfacing with the device's GPIOs. The APIs for CP210xRuntime are described below.

This document supercedes, obsoletes and takes precedences over AN223 and AN978.

The CP210x Runtime Host API provides access to the GPIO port latch, and the DLL is meant for distribution with the product containing a CP210x 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 Runtime Host API is provided in the form of a Windows Dynamic Link Library (DLL), CP210xRuntime.DLL and as a Windows static link library (.static.LIB). The host interface DLL communicates with the bridge controller device via the provided device driver and the operating system's USB stack.

Custom applications can use the CP210x Runtime API implemented in CP210xRuntime.DLL. To use functions implemented in CP210xRuntime.DLL link CP210xRuntime.LIB include CP210xRuntimeDLL.h into any source code files that call any functions implemented in CP210xRuntime.DLL and include the PATH to the location of CP210xRuntime.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 device by making a call to CP210xRT_GetNumDevices(). This call returns the number of CP210x target devices. A handle to the device must first be opened by a call to CP210xRT_Open() using an index determined from the call to CP210xRT_GetNumDevices(). The handle will be used for all subsequent accesses. When I/O operations are complete, the device handle is closed by a call to CP210xRT_Close().

Note: : Function calls into this API are blocked until completed. This can take several milliseconds depending on USB traffic.

Macro Definition Documentation

◆ CP210x_MAX_PRODUCT_STRLEN

#define CP210x_MAX_PRODUCT_STRLEN 126

Max Product string length.

◆ CP210x_MAX_SERIAL_STRLEN_S

#define CP210x_MAX_SERIAL_STRLEN_S 126

Max Serial Number string length.

◆ CP210x_MAX_SETUP_STRING_SIZE

#define CP210x_MAX_SETUP_STRING_SIZE 246

Max setup string size.

◆ CP210xDLL_API

#define CP210xDLL_API

CP210xDLL_API defination.

◆ CP210xRUNTIMEDLL_API

#define CP210xRUNTIMEDLL_API

CP210xRUNTIMEDLL_API defination.

◆ WINAPI

#define WINAPI

WINAPI defination.

Typedef Documentation

◆ CP210x_PRODUCT_STRING

typedef char CP210x_PRODUCT_STRING[126]

cp210x product string

◆ CP210x_SERIAL_STRING_S

typedef char CP210x_SERIAL_STRING_S[126]

cp210x serial string

Function Documentation

◆ CP210xRT_Close()

CP210x_STATUS CP210xRT_Close ( const HANDLE cyHandle )

Closes an open handle to the device.

Parameters

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

Returns: Returns CP210x_SUCCESS on success, or another CP210x Status Codes - manufacturing Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid

◆ CP210xRT_GetDeviceInterfaceString()

CP210x_STATUS CP210xRT_GetDeviceInterfaceString	(	const HANDLE	cyHandle,
		LPVOID	lpInterfaceString,
		LPBYTE	lpbInterfaceStringLengthInBytes,
		const BOOL	bConvertToASCII
	)

Reads and returns the Interface String directly from the device.

Parameters

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

lpInterfaceString will typically be a buffer of at least TBD characters. The returned Interface 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 lpInterfaceString must be <= CP210x_MAX_SETUP_STRING_SIZE; BUG: This is an string-UNSAFE function, not defensize against a "too small" buffer provided as the lpInterfaceString parameter.; supported on the IsMultiInterfacePartNum() CP2105 and CP2108 multi-interface CP210x devices.

Returns: Returns CP210x_SUCCESS on success, or another CP210x Status Codes - runtime Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid
CP210x_INVALID_PARAMETER	– `lpInterfaceString` or lpbInterfaceStringLengthInBytes are unexpected values
CP210x_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ CP210xRT_GetDeviceProductString()

CP210x_STATUS CP210xRT_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 CP210xRT_Open() or CreateFile()
[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 CP210x_PRODUCT_STRING or a similarly sized string of at least CP210x_MAX_PRODUCT_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 <= CP210x_MAX_SETUP_STRING_SIZE; BUG: This is an string-UNSAFE function, not defensize against a "too small" buffer provided as the lpProductString parameter.

Returns: Returns CP210x_SUCCESS on success, or another CP210x Status Codes - runtime Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid
CP210x_INVALID_PARAMETER	– lpProductString or lpbProductStringLengthInBytes are unexpected values
CP210x_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ CP210xRT_GetDeviceSerialNumber()

CP210x_STATUS CP210xRT_GetDeviceSerialNumber	(	const HANDLE	cyHandle,
		LPVOID	lpSerialNumberString,
		LPBYTE	lpbSerialNumberStringLengthInBytes,
		const BOOL	bConvertToASCII = `TRUE`
	)

Reads and returns the Serial Number String directly from the device.

Parameters

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

lpSerialNumberString will typically be an address of a string of type CP210x_SERIAL_STRING_S or a similarly sized string of at least CP210x_MAX_SERIAL_STRLEN_S characters. The returned Serial Number 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 lpSerialNumberString must be <= CP210x_MAX_SETUP_STRING_SIZE; BUG: This is an string-UNSAFE function, not defensize against a "too small" buffer provided as the lpSerialNumberString parameter.

Returns: Returns CP210x_SUCCESS on success, or another CP210x Status Codes - runtime Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid
CP210x_INVALID_PARAMETER	– lpSerialNumberString or lpbSerialNumberStringLengthInBytes are unexpected values
CP210x_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ CP210xRT_GetNumDevices()

CP210x_STATUS CP210xRT_GetNumDevices ( uint32_t * lpdwNumDevices )

Determines the number of CP210x devices connected to the system.

Parameters

[out] lpdwNumDevices a pointer to a uint32_t location to hold the returned device count

Returns: Returns CP210x_SUCCESS on success, or another CP210x Status Codes - manufacturing Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_PARAMETER	– lpdwNumDevices is an unexpected value

◆ CP210xRT_GetPartNumber()

CP210x_STATUS CP210xRT_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 CP210xRT_Open() or CreateFile()
[out]	lpbPartNum	points at a 1-byte buffer into which the SILABS_PARTNUM_CPXXXX Part Number value will be written

Returns: Returns CP210x_SUCCESS on success, or another CP210x Status Codes - runtime Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid
CP210x_INVALID_PARAMETER	– lpbPartNum is an unexpected value
CP210x_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ CP210xRT_GetReceiverMaxTimeout()

CP210x_STATUS CP210xRT_GetReceiverMaxTimeout	(	const HANDLE	cyHandle,
		uint16_t *	pReceiverMaxTimeoutInMicroseconds
	)

Reads and returns the Receiver Max Timeout directly from the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by CP210xRT_Open() or CreateFile()
[out]	pReceiverMaxTimeoutInMicroseconds	points at a buffer into which the current Receiver Max Timeout will be written

Note: xxx

Returns: Returns CP210x_SUCCESS on success, or another CP210x Status Codes - runtime Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid
CP210x_INVALID_PARAMETER	– pReceiverMaxTimeoutInMicroseconds is an unexpected value
CP210x_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ CP210xRT_Open()

CP210x_STATUS CP210xRT_Open	(	const uint32_t	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 CP210xRT_GetNumDevices().

Parameters

[in]	DeviceIndex	is the desired device's zero-based index into the device list used to determine CP210xRT_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 CP210x_SUCCESS on success, or another CP210x Status Codes - manufacturing Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_PARAMETER	– pcyHandle is an unexpected value
CP210x_DEVICE_NOT_FOUND	– the device specified by the dwDeviceIndex was not found

◆ CP210xRT_ReadLatch()

CP210x_STATUS CP210xRT_ReadLatch	(	const HANDLE	cyHandle,
		LPWORD	lpwLatch
	)

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

Parameters

[in]	cyHandle	is an open handle to the device as returned by CP210xRT_Open() or CreateFile()
[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 CP210x_SUCCESS on success, or another CP210x Status Codes - runtime Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid
CP210x_INVALID_PARAMETER	– lpwLatch is an unexpected value
CP210x_DEVICE_NOT_FOUND	– the device could not be determined to be a CP210x device
CP210x_FUNCTION_NOT_SUPPORTED	– the device does not support port latch
CP210x_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ CP210xRT_SetReceiverMaxTimeout()

CP210x_STATUS CP210xRT_SetReceiverMaxTimeout	(	const HANDLE	cyHandle,
		const uint16_t	ReceiverMaxTimeoutInMicroseconds
	)

Sets the Receiver Max Timeout directly to the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by CP210xRT_Open() or CreateFile()
[in]	ReceiverMaxTimeoutInMicroseconds	is the new Receiver Max Timeout for the device to use

Note: xxx

Returns: Returns CP210x_SUCCESS on success, or another CP210x Status Codes - runtime Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid
CP210x_INVALID_PARAMETER	– ReceiverMaxTimeoutInMicroseconds is an unexpected value
CP210x_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

◆ CP210xRT_WriteLatch()

CP210x_STATUS CP210xRT_WriteLatch	(	const HANDLE	cyHandle,
		const WORD	mask,
		const WORD	latch
	)

Sets a new current GPIO port latch value for the device.

Parameters

[in]	cyHandle	is an open handle to the device as returned by CP210xRT_Open() or CreateFile()
[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 CP210x_SUCCESS on success, or another CP210x Status Codes - runtime Return value if there is an error.

Return values

CP210x_SUCCESS	– success
CP210x_INVALID_HANDLE	– cyHandle is invalid
CP210x_DEVICE_NOT_FOUND	– the device could not be determined to be a CP210x device
CP210x_FUNCTION_NOT_SUPPORTED	– the device does not support port latch
CP210x_DEVICE_IO_FAILED	– the device failed to respond to I/O in any expected manner

Modules

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ CP210x_MAX_PRODUCT_STRLEN

◆ CP210x_MAX_SERIAL_STRLEN_S

◆ CP210x_MAX_SETUP_STRING_SIZE

◆ CP210xDLL_API

◆ CP210xRUNTIMEDLL_API

◆ WINAPI

Typedef Documentation

◆ CP210x_PRODUCT_STRING

◆ CP210x_SERIAL_STRING_S

Function Documentation

◆ CP210xRT_Close()

◆ CP210xRT_GetDeviceInterfaceString()

◆ CP210xRT_GetDeviceProductString()

◆ CP210xRT_GetDeviceSerialNumber()

◆ CP210xRT_GetNumDevices()

◆ CP210xRT_GetPartNumber()

◆ CP210xRT_GetReceiverMaxTimeout()

◆ CP210xRT_Open()

◆ CP210xRT_ReadLatch()

◆ CP210xRT_SetReceiverMaxTimeout()

◆ CP210xRT_WriteLatch()