Modules
	Product String option Types

	HidUart_GetUartStatus bitsmasks
	HidUart_GetUartStatus() bitsmasksError Status

	Number of Data Bits for UART communication
	HidUart_SetUartConfig() Number of Data Bits for UART communication

	The parity for UART communication
	HidUart_SetUartConfig() The parity for UART communication

	The number of stop bits for UART communication
	HidUart_SetUartConfig() The number of stop bits for UART communication

	The type of flow control for UART communication
	HidUart_SetUartConfig() The type of flow control for UART communication

	Read/Write Limits

	User-Customizable Field Lock Bitmasks

	Field Lock Bit Values

	Power Modes

	Flush Buffers Bitmasks

	USB Config Bitmasks
	USB Config Bitmasks. See HidUart_SetUsbConfig()

	Device-side string lengths

	Pin Config Modes

	Suspend Value Bit Values

	Suspend Mode Bit Values

	RS485 Active Levels

Macros
#define	HID_TO_UART_API
	HID to UART API. More...

#define	WINAPI
	Win API. More...

#define	HID_UART_DEVICE_STRLEN 260

#define	HID_UART_BUS_POWER_MAX 0xFA
	Power Max Value (500 mA) More...

Typedefs
typedef enum _HID_UART_STATUS *	PHID_UART_STATUS
	API Status Return Codes pointer. More...

typedef char	HID_UART_DEVICE_STR[260]
	HID_UART_DEVICE_STR. More...

typedef char	HID_UART_MFG_STR[62]
	HID to UART manufacturing string. More...

typedef char	HID_UART_PRODUCT_STR[62]
	HID to UART product string. More...

typedef char	HID_UART_SERIAL_STR[30]
	HID to UART serial string. More...

typedef void *	HID_UART_DEVICE
	HID to UART device. More...

typedef unsigned char	U8
	unsigned uint 8 More...

typedef unsigned short	U16
	unsigned uint 16 More...

Enumerations
enum	HID_UART_STATUS { HID_UART_SUCCESS = 0x00, HID_UART_DEVICE_NOT_FOUND = 0x01, HID_UART_INVALID_HANDLE = 0x02, HID_UART_INVALID_DEVICE_OBJECT = 0x03, HID_UART_INVALID_PARAMETER = 0x04, HID_UART_INVALID_REQUEST_LENGTH = 0x05, HID_UART_READ_ERROR = 0x10, HID_UART_WRITE_ERROR = 0x11, HID_UART_READ_TIMED_OUT = 0x12, HID_UART_WRITE_TIMED_OUT = 0x13, HID_UART_DEVICE_IO_FAILED = 0x14, HID_UART_DEVICE_ACCESS_ERROR = 0x15, HID_UART_DEVICE_NOT_SUPPORTED = 0x16, HID_UART_INVALID_CONFIG_VERSION = 0x17, HID_UART_DEVICE_ALREADY_OPENED = 0x22, HID_UART_UNKNOWN_ERROR = SILABS_STATUS_UNKNOWN_ERROR }

Functions
HID_UART_STATUS	HidUart_GetNumDevices (LPDWORD lpdwNumDevices, const WORD vid, const WORD pid)
	Determines the number of devices connected to the system with matching Vendor ID and Product ID. More...

HID_UART_STATUS	HidUart_GetString (const DWORD deviceNum, const WORD vid, const WORD pid, char *deviceString, const DWORD options)
	This function returns a null-terminated vendor ID string, product ID string, serial number string, device path string, manufacturer string, or product string for the device specified by an index passed in deviceNum. More...

HID_UART_STATUS	HidUart_GetOpenedString (const HID_UART_DEVICE device, char *deviceString, const DWORD options)
	This function returns a null-terminated vendor ID string, product ID string, serial number string, device path string, manufacturer string, or product string for the device specified by device. More...

HID_UART_STATUS	HidUart_GetIndexedString (const DWORD deviceNum, const WORD vid, const WORD pid, const DWORD stringIndex, char *deviceString)
	This function returns a null-terminated USB string descriptor for the device specified by an index passed in deviceNum. (Windows/Linux only) More...

HID_UART_STATUS	HidUart_GetOpenedIndexedString (const HID_UART_DEVICE device, const DWORD stringIndex, char *deviceString)
	This function returns a null-terminated USB string descriptor for the device specified by device. (Windows/Linux only) More...

HID_UART_STATUS	HidUart_GetAttributes (const DWORD deviceNum, const WORD vid, const WORD pid, WORD deviceVid, WORD devicePid, WORD *pDeviceReleaseNumber)
	This function returns the device vendor ID, product ID, and device release number for the device specified by an index passed in deviceNum. More...

HID_UART_STATUS	HidUart_GetOpenedAttributes (const HID_UART_DEVICE device, WORD pDeviceVid, WORD pDevicePid, WORD *pDeviceReleaseNumber)
	This function returns the device vendor ID, product ID, and device release number for the opened device. More...

HID_UART_STATUS	HidUart_Open (HID_UART_DEVICE *pdevice, const DWORD deviceNum, const WORD vid, const WORD pid)
	Opens a device using a device number between 0 and HidUart_GetNumDevices() - 1, enables the UART, and returns a device object pointer which will be used for subsequent accesses. More...

HID_UART_STATUS	HidUart_Close (const HID_UART_DEVICE device)
	Closes an opened device using the device object pointer provided by HidUart_Open(). More...

HID_UART_STATUS	HidUart_IsOpened (const HID_UART_DEVICE device, BOOL *pbIsOpened)
	Returns the device opened status. More...

HID_UART_STATUS	HidUart_SetUartEnable (const HID_UART_DEVICE device, const BOOL enable)
	Enables or disables the UART. More...

HID_UART_STATUS	HidUart_GetUartEnable (const HID_UART_DEVICE device, BOOL *penable)
	Returns the UART enable status. More...

HID_UART_STATUS	HidUart_Read (const HID_UART_DEVICE device, BYTE buffer, const DWORD numBytesToRead, DWORD pNumBytesRead)
	Reads the available number of bytes into the supplied buffer and returns the number of bytes read which can be less than the number of bytes requested. This function returns synchronously after reading the requested number of bytes or after the timeout duration has elapsed. Read and write timeouts can be set using HidUart_SetTimeouts(). More...

HID_UART_STATUS	HidUart_Write (const HID_UART_DEVICE device, BYTE buffer, const DWORD numBytesToWrite, DWORD pNumBytesWritten)
	Write the specified number of bytes from the supplied buffer to the device. This function returns synchronously after writing the requested number of bytes or after the timeout duration has elapsed. Read and write timeouts can be set using HidUart_SetTimeouts(). More...

HID_UART_STATUS	HidUart_FlushBuffers (const HID_UART_DEVICE device, const BOOL bFlushTransmit, const BOOL bFlushReceive)
	Flushes the receive buffer in the device and the HID driver and/or the transmit buffer in the device. More...

HID_UART_STATUS	HidUart_CancelIo (const HID_UART_DEVICE device)
	cancels any pending HID reads and writes. (Windows only) More...

HID_UART_STATUS	HidUart_SetTimeouts (const HID_UART_DEVICE device, const DWORD ReadTimeoutInMilliseconds, const DWORD WriteTimeoutInMilliseconds)
	Sets the read and write timeouts. More...

HID_UART_STATUS	HidUart_GetTimeouts (const HID_UART_DEVICE device, DWORD pReadTimeoutInMilliseconds, DWORD pWriteTimeoutInMilliseconds)
	Returns the current read and write timeouts specified in milliseconds. More...

HID_UART_STATUS	HidUart_GetUartStatus (const HID_UART_DEVICE device, WORD transmitFifoSize, WORD receiveFifoSize, BYTE errorStatus, BYTE lineBreakStatus)
	Returns the number of bytes held in the device receive and transmit FIFO. Returns the parity/error status and line break status. More...

HID_UART_STATUS	HidUart_SetUartConfig (const HID_UART_DEVICE device, const DWORD baudRate, const BYTE dataBits, const BYTE parity, const BYTE stopBits, const BYTE flowControl)
	Sets the baud rate, data bits, parity, stop bits, and flow control. More...

HID_UART_STATUS	HidUart_GetUartConfig (const HID_UART_DEVICE device, DWORD pBaudRate, BYTE pDataBits, BYTE pParity, BYTE pStopBits, BYTE *pFlowControl)
	Gets the baud rate, data bits, parity, stop bits, and flow control. More...

HID_UART_STATUS	HidUart_StartBreak (const HID_UART_DEVICE device, const BYTE DurationInMilliseconds)
	Causes the device to transmit a line break, holding the TX pin low, for the specified duration in milliseconds. More...

HID_UART_STATUS	HidUart_StopBreak (const HID_UART_DEVICE device)
	Stops the device from transmitting a line break. More...

HID_UART_STATUS	HidUart_Reset (const HID_UART_DEVICE device)
	Initiates a full device reset. More...

HID_UART_STATUS	HidUart_ReadLatch (const HID_UART_DEVICE device, WORD *pLatchValue)
	Get the current port latch value from the device. More...

HID_UART_STATUS	HidUart_WriteLatch (const HID_UART_DEVICE device, const WORD LatchValue, const WORD LatchMask)
	Sets the current port latch value to the device. More...

HID_UART_STATUS	HidUart_GetPartNumber (const HID_UART_DEVICE device, BYTE pPartNumber, BYTE pVersion)
	Retrieves the part number and version of the CP211x device. More...

HID_UART_STATUS	HidUart_GetLibraryVersion (BYTE pMajor, BYTE pMinor, BOOL *pIsReleaseBuild)
	Returns the HID-to-UART Interface Library version information. More...

HID_UART_STATUS	HidUart_GetHidLibraryVersion (BYTE pMajor, BYTE pMinor, BOOL *pIsReleaseBuild)
	Returns the version of the underlying HID Device Interface Library that is currently in use. More...

HID_UART_STATUS	HidUart_GetHidGuid (void *pHIDGuid)
	Return the GUID for HIDClass devices ("return the HID GUID") (Windows only) More...

HID_UART_STATUS	HidUart_SetLock (const HID_UART_DEVICE device, const WORD lock)
	Permanently locks/disables device customization. More...

HID_UART_STATUS	HidUart_GetLock (const HID_UART_DEVICE device, WORD *lock)
	Returns the device customization lock status. More...

HID_UART_STATUS	HidUart_SetUsbConfig (const HID_UART_DEVICE device, const WORD vid, const WORD pid, const BYTE power, const BYTE powerMode, const WORD releaseVersion, const BYTE flushBuffers, const BYTE mask)
	Allows one-time customization of the USB configuration, which includes vendor ID, product ID, power, power mode, release version, and flush buffers setting.Each field can be independently programmed one time each via the mask field. More...

HID_UART_STATUS	HidUart_GetUsbConfig (const HID_UART_DEVICE device, WORD pVid, WORD pPid, BYTE pPower, BYTE pPowerMode, WORD pReleaseVersion, BYTE pFlushBuffers)
	Retrieves USB configuration, which includes vendor ID, product ID, power, power mode, release version, and flush buffers setting. More...

HID_UART_STATUS	HidUart_SetManufacturingString (const HID_UART_DEVICE device, char *manufacturingString, const BYTE strlen)
	Allows one-time customization of the USB manufacturing string. More...

HID_UART_STATUS	HidUart_GetManufacturingString (const HID_UART_DEVICE device, char manufacturingString, BYTE strlen)
	Retrieves the USB manufacturing string. More...

HID_UART_STATUS	HidUart_SetProductString (const HID_UART_DEVICE device, char *productString, const BYTE strlen)
	Allows one-time customization of the USB product string. More...

HID_UART_STATUS	HidUart_GetProductString (const HID_UART_DEVICE device, char productString, BYTE strlen)
	Retrieves the USB product string. More...

HID_UART_STATUS	HidUart_SetSerialString (const HID_UART_DEVICE device, char *serialString, const BYTE strlen)
	Allows one-time customization of the USB serial number string. More...

HID_UART_STATUS	HidUart_GetSerialString (const HID_UART_DEVICE device, char serialString, BYTE strlen)
	Retrieves the USB Serial Number string. More...

Detailed Description

The Silicon Labs HID-to-UART interface library provides a simple API to configure and operate CP2110 and CP2114 devices.

The library provides interface abstraction so that users can develop their application without writing any USB HID code. Silicon Labs provides both static and dynamic libraries implementing the CP2110 and CP2114 Interface Specification for Windows, Mac OS X, and Linux. Similarly, various include files are provided to import library functions into C#.NET and Visual Basic.NET.

The APIs for SLABHIDtoUART interface library are described below.

This document supercedes, obsoletes and takes precedences over AN433 https://www.silabs.com/documents/public/application-notes/AN433-CP2110-4-HID-to-UART-API-Spec.pdf.

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

Custom applications can use the SLABHIDtoUART API implemented in SLABHIDtoUART.DLL. To use functions implemented in SLABHIDtoUART.DLL link SLABHIDtoUART.LIB include SLABHIDtoUART.h into any source code files that call any functions implemented in SLABHIDtoUART.DLL and include the PATH to the location of SLABHIDtoUART.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 device/s by making a call to HidUart_GetNumDevices(). This call returns the number of CP2110 and CP2114 target devices. This number is used as a range when calling HidUart_GetProductString() to build a list of devices connected to the host machine. A handle to the device must first be opened by a call to HidUart_Open() using an index determined from the call to HidUart_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 HidUart_Close().

Macro Definition Documentation

◆ HID_TO_UART_API

#define HID_TO_UART_API

HID to UART API.

◆ HID_UART_BUS_POWER_MAX

#define HID_UART_BUS_POWER_MAX 0xFA

Power Max Value (500 mA)

Max HID to UART bus power

◆ HID_UART_DEVICE_STRLEN

#define HID_UART_DEVICE_STRLEN 260

CP210x Maximum Device-side string length

◆ WINAPI

#define WINAPI

Win API.

Typedef Documentation

◆ HID_UART_DEVICE

HID_UART_DEVICE

HID to UART device.

◆ HID_UART_DEVICE_STR

HID_UART_DEVICE_STR

HID_UART_DEVICE_STR.

◆ HID_UART_MFG_STR

HID_UART_MFG_STR

HID to UART manufacturing string.

◆ HID_UART_PRODUCT_STR

HID_UART_PRODUCT_STR

HID to UART product string.

◆ HID_UART_SERIAL_STR

HID_UART_SERIAL_STR

HID to UART serial string.

◆ PHID_UART_STATUS

PHID_UART_STATUS

API Status Return Codes pointer.

◆ U16

U16

unsigned uint 16

◆ U8

U8

unsigned uint 8

Enumeration Type Documentation

◆ HID_UART_STATUS

enum HID_UART_STATUS

Enumerator
HID_UART_SUCCESS	Success.
HID_UART_DEVICE_NOT_FOUND	the specified device was not found
HID_UART_INVALID_HANDLE	an handle parameter was not valid
HID_UART_INVALID_DEVICE_OBJECT	the device object pointer does not match the address of a valid HID - to - UART device
HID_UART_INVALID_PARAMETER	a parameter was not valid
HID_UART_INVALID_REQUEST_LENGTH	the specified number of bytes to read or write is invalid.
HID_UART_READ_ERROR	the read was not successful and did not time out.
HID_UART_WRITE_ERROR	the write was not successful.
HID_UART_READ_TIMED_OUT	a read failed to return the number of bytes requested before the read timeout elapsed.
HID_UART_WRITE_TIMED_OUT	a write failed to complete sending the number of bytes requested before the write timeout elapsed.
HID_UART_DEVICE_IO_FAILED	host was unable to get or set a feature report.
HID_UART_DEVICE_ACCESS_ERROR	the device or device property could not be accessed.Either the device is not opened, already opened when trying to open, or an error occurred when trying to get HID information.
HID_UART_DEVICE_NOT_SUPPORTED	the current device does not support the corresponding action
HID_UART_INVALID_CONFIG_VERSION	tbd
HID_UART_DEVICE_ALREADY_OPENED	the specified device is already (exclusively) opened
HID_UART_UNKNOWN_ERROR	This value should never be returned.

Function Documentation

◆ HidUart_CancelIo()

HID_UART_STATUS HidUart_CancelIo ( const HID_UART_DEVICE device )

cancels any pending HID reads and writes. (Windows only)

Parameters

[in] device is the Device object pointer as returned by HidUart_Open().

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object

◆ HidUart_Close()

HID_UART_STATUS HidUart_Close ( const HID_UART_DEVICE device )

Closes an opened device using the device object pointer provided by HidUart_Open().

Parameters

[in] device is the Device object pointer as returned by HidUart_Open().

Note: The device parameter is invalid after calling HidUart_Close(). Set device to NULL after calling HidUart_Close().

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_HANDLE	– failed, the device specified by device does not have a valid handle
HID_UART_DEVICE_ACCESS_ERROR	– tbd

◆ HidUart_FlushBuffers()

HID_UART_STATUS HidUart_FlushBuffers	(	const HID_UART_DEVICE	device,
		const BOOL	bFlushTransmit,
		const BOOL	bFlushReceive
	)

Flushes the receive buffer in the device and the HID driver and/or the transmit buffer in the device.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	bFlushTransmit	Set to TRUE to flush the device transmit buffer.
[in]	bFlushReceive	Set to TRUE to flush the device receive buffer and HID receive buffer.

Note: Flush means purge, or discard. It does not mean drain, hurry-along or wait for completion.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_GetAttributes()

HID_UART_STATUS HidUart_GetAttributes	(	const DWORD	deviceNum,
		const WORD	vid,
		const WORD	pid,
		WORD *	deviceVid,
		WORD *	devicePid,
		WORD *	pDeviceReleaseNumber
	)

This function returns the device vendor ID, product ID, and device release number for the device specified by an index passed in deviceNum.

Parameters

[in]	deviceNum	Index of the device for which the string is desired.
[in]	vid	is the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]	pid	is the 2-byte Product ID value, filter device results by this Product ID.
[out]	deviceVid	- returns the 2-byte Vendor ID value from the device.
[out]	devicePid	- returns the 2-byte Product ID value from the device.
[out]	pDeviceReleaseNumber	points at a 2-byte buffer into which the USB device bcdVersion, or device release number, value will be written

Note: If both vid and pid are zero (0x0000), devices will NOT be filtered by vid/pid.; A successfully returned pDeviceReleaseNumber is in binary-coded decimal (BCD).

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_DEVICE_NOT_FOUND	– deviceNum is an unexpected value
HID_UART_DEVICE_ALREADY_OPENED	– the specified device is already (exclusively) opened
HID_UART_INVALID_PARAMETER	– deviceVid, devicePid and/or pDeviceReleaseNumber is an unexpected value

◆ HidUart_GetHidGuid()

HID_UART_STATUS HidUart_GetHidGuid ( void * pHIDGuid )

Return the GUID for HIDClass devices ("return the HID GUID") (Windows only)

The HID GUID can be used to register for surprise removal notifications. See MSDNURL.

Parameters

[out] pHIDGuid points at a caller-allocated GUID buffer into which the HID GUID value will be written

Note: BUG: This is an buffer-UNSAFE function, not defensive against a "too small" buffer provided as the pHIDGuid parameter.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_PARAMETER	– pHIDGuid is an unexpected value

◆ HidUart_GetHidLibraryVersion()

HID_UART_STATUS HidUart_GetHidLibraryVersion	(	BYTE *	pMajor,
		BYTE *	pMinor,
		BOOL *	pIsReleaseBuild
	)

Returns the version of the underlying HID Device Interface Library that is currently in use.

Parameters

[out]	pMajor	points to a 1-byte buffer into which the major library version is written and returned.
[out]	pMinor	points to a 1-byte buffer into which the minor library version value is written and returned.
[out]	pIsReleaseBuild	points to a 4-byte buffer into which TRUE if the library is a release build, otherwise the library is a Debug build is written and returned.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_PARAMETER	– pMajor and/or pMinor and/or pIsReleaseBuild is an unexpected value

◆ HidUart_GetIndexedString()

HID_UART_STATUS HidUart_GetIndexedString	(	const DWORD	deviceNum,
		const WORD	vid,
		const WORD	pid,
		const DWORD	stringIndex,
		char *	deviceString
	)

This function returns a null-terminated USB string descriptor for the device specified by an index passed in deviceNum. (Windows/Linux only)

Parameters

[in]	deviceNum	Index of the device for which the string is desired.
[in]	vid	is the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]	pid	is the 2-byte Product ID value, filter device results by this Product ID.
[in]	stringIndex	- Specifies the device-specific index of the USB string descriptor to return.
[out]	deviceString	- Variable of type Product String option Types which will contain a NULL terminated device descriptor string on return. The string is 260 bytes on Windows and 512 bytes on Linux.

Note: If both vid and pid are set to 0x0000, then HID devices will not be filtered by VID/PID.; BUG: This is an string-UNSAFE function, not defensive against a "too small" buffer provided as the deviceString parameter.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_DEVICE_NOT_FOUND	– deviceNum is an unexpected value
HID_UART_DEVICE_ACCESS_ERROR	– tbd
HID_UART_INVALID_PARAMETER	– deviceString is an unexpected value

◆ HidUart_GetLibraryVersion()

HID_UART_STATUS HidUart_GetLibraryVersion	(	BYTE *	pMajor,
		BYTE *	pMinor,
		BOOL *	pIsReleaseBuild
	)

Returns the HID-to-UART Interface Library version information.

Parameters

[out]	pMajor	points to a 1-byte buffer into which the major library version is written and returned.
[out]	pMinor	points to a 1-byte buffer into which the minor library version value is written and returned.
[out]	pIsReleaseBuild	points to a 4-byte buffer into which TRUE if the library is a release build, otherwise the library is a Debug build is written and returned.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_PARAMETER	– pMajor and/or pMinor and/or pIsReleaseBuild is an unexpected value

◆ HidUart_GetLock()

HID_UART_STATUS HidUart_GetLock	(	const HID_UART_DEVICE	device,
		WORD *	lock
	)

Returns the device customization lock status.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	lock	- Returns a bitmask specifying which fields are locked (HID_UART_LOCK_LOCKED). See User-Customizable Field Lock Bitmasks.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– lock is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_GetManufacturingString()

HID_UART_STATUS HidUart_GetManufacturingString	(	const HID_UART_DEVICE	device,
		char *	manufacturingString,
		BYTE *	strlen
	)

Retrieves the USB manufacturing string.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	manufacturingString	Variable of type HID_UART_CP2110/4_MFG_STR, a 62-byte character buffer that will contain the ASCII manufacturing string.
[out]	strlen	Returns the length of the string in bytes.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– manufacturingString and/or strlen is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_GetNumDevices()

HID_UART_STATUS HidUart_GetNumDevices	(	LPDWORD	lpdwNumDevices,
		const WORD	vid,
		const WORD	pid
	)

Determines the number of devices connected to the system with matching Vendor ID and Product ID.

Parameters

[out]	lpdwNumDevices	a pointer to a uint32_t location to hold the returned device count
[in]	vid	is the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]	pid	is the 2-byte Product ID value, filter device results by this Product ID.

Note: If both vid and pid are set to 0x0000, then HID devices will not be filtered by VID/PID.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_PARAMETER	– lpdwNumDevices is an unexpected value

◆ HidUart_GetOpenedAttributes()

HID_UART_STATUS HidUart_GetOpenedAttributes	(	const HID_UART_DEVICE	device,
		WORD *	pDeviceVid,
		WORD *	pDevicePid,
		WORD *	pDeviceReleaseNumber
	)

This function returns the device vendor ID, product ID, and device release number for the opened device.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	pDeviceVid	- returns the 2-byte Vendor ID value from the device.
[out]	pDevicePid	- returns the 2-byte Product ID value from the device.
[out]	pDeviceReleaseNumber	points at a 2-byte buffer into which the USB device bcdVersion, or device release number, value will be written

Note: A successfully returned pDeviceReleaseNumber is in binary-coded decimal (BCD).

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– pDeviceVid, pDevicePid and/or pDeviceReleaseNumber is an unexpected value

◆ HidUart_GetOpenedIndexedString()

HID_UART_STATUS HidUart_GetOpenedIndexedString	(	const HID_UART_DEVICE	device,
		const DWORD	stringIndex,
		char *	deviceString
	)

This function returns a null-terminated USB string descriptor for the device specified by device. (Windows/Linux only)

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	stringIndex	- Specifies the device-specific index of the USB string descriptor to return.
[out]	deviceString	- Variable of type Product String option Types which will contain a NULL terminated device descriptor string on return. The string is 260 bytes on Windows and 512 bytes on Linux.

Note: BUG: This is an string-UNSAFE function, not defensive against a "too small" buffer provided as the deviceString parameter.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_DEVICE_ACCESS_ERROR	– tbd
HID_UART_INVALID_PARAMETER	– deviceString is an unexpected value

◆ HidUart_GetOpenedString()

HID_UART_STATUS HidUart_GetOpenedString	(	const HID_UART_DEVICE	device,
		char *	deviceString,
		const DWORD	options
	)

This function returns a null-terminated vendor ID string, product ID string, serial number string, device path string, manufacturer string, or product string for the device specified by device.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	deviceString	- Variable of type Product String option Types which will contain a NULL terminated ASCII device string on return. The string is 260 bytes on Windows and 512 bytes on macos and Linux.
[in]	options	- Determines if deviceString contains a vendor ID string, product ID string, serial number string, device path string, manufacturer string, or product string. See Product String option Types

Note: BUG: This is an string-UNSAFE function, not defensive against a "too small" buffer provided as the deviceString parameter.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_DEVICE_ACCESS_ERROR	– tbd
HID_UART_INVALID_PARAMETER	– deviceString and/or options is an unexpected value

◆ HidUart_GetPartNumber()

HID_UART_STATUS HidUart_GetPartNumber	(	const HID_UART_DEVICE	device,
		BYTE *	pPartNumber,
		BYTE *	pVersion
	)

Retrieves the part number and version of the CP211x device.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	pPartNumber	points to a 1-byte buffer into which the device part number is written and returned. see Pin Config Mode Array indices.
[out]	pVersion	points to a 1-byte buffer into which the version value is written and returned.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– pPartNumber and/or pVersion is an unexpected value

◆ HidUart_GetProductString()

HID_UART_STATUS HidUart_GetProductString	(	const HID_UART_DEVICE	device,
		char *	productString,
		BYTE *	strlen
	)

Retrieves the USB product string.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	productString	Variable of type HID_UART_CP2110/4_PRODUCT_STR, a 62-byte character buffer that will contain the ASCII product string.
[out]	strlen	Returns the length of the string in bytes.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– productString and/or strlen is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_GetSerialString()

HID_UART_STATUS HidUart_GetSerialString	(	const HID_UART_DEVICE	device,
		char *	serialString,
		BYTE *	strlen
	)

Retrieves the USB Serial Number string.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	serialString	- Variable of type HID_UART_CP2110/4_SERIAL_STR, a 30-byte character buffer that will contain the Unicode product string.
[out]	strlen	- Returns the length of the string in bytes.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– serialString and/or strlen is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_GetString()

HID_UART_STATUS HidUart_GetString	(	const DWORD	deviceNum,
		const WORD	vid,
		const WORD	pid,
		char *	deviceString,
		const DWORD	options
	)

This function returns a null-terminated vendor ID string, product ID string, serial number string, device path string, manufacturer string, or product string for the device specified by an index passed in deviceNum.

The index for the first device is 0 and the last device is the value returned by HidUart_GetNumDevices() - 1.

Parameters

[in]	deviceNum	Index of the device for which the string is desired.
[in]	vid	is the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]	pid	is the 2-byte Product ID value, filter device results by this Product ID.
[out]	deviceString	- Variable of type Product String option Types which will contain a NULL terminated ASCII device string on return. The string is 260 bytes on Windows and 512 bytes on macos and Linux.
[in]	options	- Determines if deviceString contains a vendor ID string, product ID string, serial number string, device path string, manufacturer string, or product string. See Product String option Types

Note: If both vid and pid are set to 0x0000, then HID devices will not be filtered by VID/PID.; BUG: This is an string-UNSAFE function, not defensive against a "too small" buffer provided as the deviceString parameter.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_DEVICE_NOT_FOUND	– deviceNum is an unexpected value
HID_UART_DEVICE_ALREADY_OPENED	– the specified device is already (exclusively) opened
HID_UART_DEVICE_ACCESS_ERROR	– tbd
HID_UART_INVALID_PARAMETER	– deviceString and/or options is an unexpected value

◆ HidUart_GetTimeouts()

HID_UART_STATUS HidUart_GetTimeouts	(	const HID_UART_DEVICE	device,
		DWORD *	pReadTimeoutInMilliseconds,
		DWORD *	pWriteTimeoutInMilliseconds
	)

Returns the current read and write timeouts specified in milliseconds.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	pReadTimeoutInMilliseconds	points to a buffer into which the HidUart_ReadLatch() operation timeout in milliseconds will be written.
[out]	pWriteTimeoutInMilliseconds	points to a buffer into which the HidUart_WriteLatch() operation timeout in milliseconds will be written.

Note: Read and write timeouts are maintained for each device but are not persistent across HidUart_Open()/HidUart_Close().

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– pReadTimeoutInMilliseconds and/or pWriteTimeoutInMilliseconds is an unexpected value

◆ HidUart_GetUartConfig()

HID_UART_STATUS HidUart_GetUartConfig	(	const HID_UART_DEVICE	device,
		DWORD *	pBaudRate,
		BYTE *	pDataBits,
		BYTE *	pParity,
		BYTE *	pStopBits,
		BYTE *	pFlowControl
	)

Gets the baud rate, data bits, parity, stop bits, and flow control.

Refer to the device data sheet for a list of supported configuration settings.

◆ HidUart_GetUartEnable()

HID_UART_STATUS HidUart_GetUartEnable	(	const HID_UART_DEVICE	device,
		BOOL *	penable
	)

Returns the UART enable status.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	penable	points to a buffer into which a Boolean flag where TRUE means the UART is enabled, and FALSE means is is not will be written

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– penable is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_GetUartStatus()

HID_UART_STATUS HidUart_GetUartStatus	(	const HID_UART_DEVICE	device,
		WORD *	transmitFifoSize,
		WORD *	receiveFifoSize,
		BYTE *	errorStatus,
		BYTE *	lineBreakStatus
	)

Returns the number of bytes held in the device receive and transmit FIFO. Returns the parity/error status and line break status.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	transmitFifoSize	- Returns the number of bytes currently held in the device transmit FIFO.
[out]	receiveFifoSize	- Returns the number of bytes currently held in the device receive FIFO.
[out]	errorStatus	- Returns an error status bitmap describing HID_UART_PARITY_ERROR parity and HID_UART_OVERRUN_ERROR overrun errors function clears the errors.
[out]	lineBreakStatus	- Returns HID_UART_LINE_BREAK_ACTIVE if line break is currently active and HID_UART_LINE_BREAK_INACTIVE otherwise.

Note: The transmitFifoSize and receiveFifoSize only apply to data held in the device FIFOs; they do not include data queued in the HID driver or interface library; Calling HidUart_GetUartStatus() reports the current errorStatus and then clears the errors.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– transmitFifoSize, and/or receiveFifoSize, and/or errorStatus, and/or lineBreakStatus is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_GetUsbConfig()

HID_UART_STATUS HidUart_GetUsbConfig	(	const HID_UART_DEVICE	device,
		WORD *	pVid,
		WORD *	pPid,
		BYTE *	pPower,
		BYTE *	pPowerMode,
		WORD *	pReleaseVersion,
		BYTE *	pFlushBuffers
	)

Retrieves USB configuration, which includes vendor ID, product ID, power, power mode, release version, and flush buffers setting.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	pVid	points to a 1-byte buffer into which the Vendor ID is written and returned.
[out]	pPid	points to a 1-byte buffer into which the Product ID is written and returned.
[out]	pPower	points to a 1-byte buffer into which the power value which specifies the current requested by the device IFF the device is configured to be bus powered is written and returned. See HID_UART_BUS_POWER_MAX.
[out]	pPowerMode	points to a 1-byte buffer into which the Power Mode value to configure the device as bus powered or self powered is written and returned. See Power Modes.
[out]	pReleaseVersion	points to a 1-byte buffer into which the Major.Minor Release Version value is written and returned.
[out]	pFlushBuffers	is the 2-byte Flush Buffers value is written and returned. See Flush Buffers Bitmasks.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– pVid and/or pPid and/or pPower and/or pPowerMode and/or pReleaseVersion and/or pFlushBuffers is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_IsOpened()

HID_UART_STATUS HidUart_IsOpened	(	const HID_UART_DEVICE	device,
		BOOL *	pbIsOpened
	)

Returns the device opened status.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	pbIsOpened	points to a buffer into which a Boolean flag where TRUE means the device object pointer is valid and the device has been opened using HidUart_Open(), and FALSE means it has not will be written

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– pbIsOpened is an unexpected value

◆ HidUart_Open()

HID_UART_STATUS HidUart_Open	(	HID_UART_DEVICE *	pdevice,
		const DWORD	deviceNum,
		const WORD	vid,
		const WORD	pid
	)

Opens a device using a device number between 0 and HidUart_GetNumDevices() - 1, enables the UART, and returns a device object pointer which will be used for subsequent accesses.

Parameters

[out]	pdevice	- Returns a pointer to a HID-to-UART device object for subsequent accesses to the device.
[in]	deviceNum	- Zero-based device index, between 0 and (HidUart_GetNumDevices() - 1).
[in]	vid	is the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]	pid	is the 2-byte Product ID value, filter device results by this Product ID.

Note: If both vid and pid are zero (0x0000), devices will NOT be filtered by vid/pid.; Be careful when opening a device. Any HID device may be opened by this library. However, if the device is not actually a CP211x, use of this library will cause undesirable results. The best course of action would be to designate a unique VID/PID for CP211x devices only. The application should then filter devices using this VID/PID.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_DEVICE_NOT_FOUND	– deviceNum is an unexpected value
HID_UART_DEVICE_ACCESS_ERROR	– Could not access device (i.e. already opened?)
HID_UART_DEVICE_NOT_SUPPORTED	– Per device's PartNum only support CP2110 and CP2114 devices
HID_UART_INVALID_PARAMETER	– pdevice is an unexpected value

◆ HidUart_Read()

HID_UART_STATUS HidUart_Read	(	const HID_UART_DEVICE	device,
		BYTE *	buffer,
		const DWORD	numBytesToRead,
		DWORD *	pNumBytesRead
	)

Reads the available number of bytes into the supplied buffer and returns the number of bytes read which can be less than the number of bytes requested. This function returns synchronously after reading the requested number of bytes or after the timeout duration has elapsed. Read and write timeouts can be set using HidUart_SetTimeouts().

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	buffer	- Address of a buffer to be filled with read data.
[in]	numBytesToRead	- Number of bytes to read from the device into the buffer (1-32768) value must be less than or equal to the size of buffer.
[out]	pNumBytesRead	points to a buffer into which the number of bytes actually read into the buffer will be written.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– buffer and/or pNumBytesRead is an unexpected value
HID_UART_INVALID_REQUEST_LENGTH	– numBytesToRead must be in the range (HID_UART_MIN_READ_SIZE /1 - HID_UART_MAX_READ_SIZE /32768)
HID_UART_READ_ERROR	– tbd
HID_UART_READ_TIMED_OUT	– the number of bytes read is less than the number of bytes requested and the read timeout has elapsed.

◆ HidUart_ReadLatch()

HID_UART_STATUS HidUart_ReadLatch	(	const HID_UART_DEVICE	device,
		WORD *	pLatchValue
	)

Get the current port latch value from the device.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[out]	pLatchValue	points to a 2-byte buffer into which the port latch value is written and returned. see Pin Config Mode Array indices.

The port latch value (Logic High = 1, Logic Low = 0) as a GPIO input or flow control pin that is an input, then the corresponding bit represents the input value. If a pin is configured as a GPIO output pin or a flow control pin that is an output, then the corresponding bit represents the logic level driven on the pin.

See Pin Config Mode Array indices Port Latch Pin Definition for more information on configuring GPIO and flow control pins. Bits 9 and 15 of *pLatchValue are ignored.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– pLatchValue is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_Reset()

HID_UART_STATUS HidUart_Reset ( const HID_UART_DEVICE device )

Initiates a full device reset.

Transmit and receive FIFOs will be cleared, UART settings will be reset to default values (115200, 8N1, no flow control), and the device will re-enumerate.

Parameters

[in] device is the Device object pointer as returned by HidUart_Open().

Note: The device parameter is stale after successfully calling HidUart_Reset(). ??TBD Can calose be called? should close be called? Set device to NULL after calling HidUart_Reset or HidUart_Close()?.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_SetLock()

HID_UART_STATUS HidUart_SetLock	(	const HID_UART_DEVICE	device,
		const WORD	lock
	)

Permanently locks/disables device customization.

When this function is successfully called, the specified fields are fully locked and cannot be further customized. The user customization functions can be called and may return HID_UART_SUCCESS even though the device was not programmed. Call the function's corresponding get function to verify that customization was successful. Each field is stored in one time programmable memory (OTP) and can only be customized once. After a field is customized, the corresponding lock bits are set to 0.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open(). See User-Customizable Field Lock Bitmasks.
[in]	lock	- Bitmask specifying which fields can be customized/programmed (HID_UART_LOCK_UNLOCKED) and which fields are already customized (HID_UART_LOCK_LOCKED).

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_SetManufacturingString()

HID_UART_STATUS HidUart_SetManufacturingString	(	const HID_UART_DEVICE	device,
		char *	manufacturingString,
		const BYTE	strlen
	)

Allows one-time customization of the USB manufacturing string.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	manufacturingString	Variable of type HID_UART_CP2110/4_MFG_STR, a 62-byte character buffer containing the ASCII manufacturing string..
[in]	strlen	The length of manufacturingString in bytes.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– manufacturingString and/or strlen is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_SetProductString()

HID_UART_STATUS HidUart_SetProductString	(	const HID_UART_DEVICE	device,
		char *	productString,
		const BYTE	strlen
	)

Allows one-time customization of the USB product string.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	productString	Variable of type HID_UART_CP2110/4_PRODUCT_STR, a 62-byte character buffer containing the ASCII product string.
[in]	strlen	The length of productString in bytes.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– productString and/or strlen is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_SetSerialString()

HID_UART_STATUS HidUart_SetSerialString	(	const HID_UART_DEVICE	device,
		char *	serialString,
		const BYTE	strlen
	)

Allows one-time customization of the USB serial number string.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	serialString	- Variable of type HID_UART_CP2110/4_SERIAL_STR, a 30-byte character buffer containing the ASCII serial number string.
[in]	strlen	- The length of serialString in bytes.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– serialString and/or strlen is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_SetTimeouts()

HID_UART_STATUS HidUart_SetTimeouts	(	const HID_UART_DEVICE	device,
		const DWORD	ReadTimeoutInMilliseconds,
		const DWORD	WriteTimeoutInMilliseconds
	)

Sets the read and write timeouts.

Timeouts are used for HidUart_ReadLatch() and HidUart_WriteLatch(). The default value for timeouts is 1000 ms, but timeouts can be set to wait for any number of milliseconds between 0 and 0xFFFFFFFF.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	ReadTimeoutInMilliseconds	is the HidUart_ReadLatch() operation timeout in milliseconds.
[in]	WriteTimeoutInMilliseconds	is the 2-byte Product ID value.

Note: Read and write timeouts are maintained for each device but are not persistent across HidUart_Open()/HidUart_Close().; If read timeouts are set to a large value and no data is received, then the application may appear unresponsive. It is recommended to set timeouts appropriately before using the device.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object

◆ HidUart_SetUartConfig()

HID_UART_STATUS HidUart_SetUartConfig	(	const HID_UART_DEVICE	device,
		const DWORD	baudRate,
		const BYTE	dataBits,
		const BYTE	parity,
		const BYTE	stopBits,
		const BYTE	flowControl
	)

Sets the baud rate, data bits, parity, stop bits, and flow control.

Refer to the device data sheet for a list of supported configuration settings.

◆ HidUart_SetUartEnable()

HID_UART_STATUS HidUart_SetUartEnable	(	const HID_UART_DEVICE	device,
		const BOOL	enable
	)

Enables or disables the UART.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	enable	- Set to TRUE/non-zer0 to enable the UART, FALSE/0 to disable

Note: Enabling or disabling the UART will flush the UART FIFOs if the flushBuffers parameter is enabled by calling HidUart_SetUsbConfig().

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_SetUsbConfig()

HID_UART_STATUS HidUart_SetUsbConfig	(	const HID_UART_DEVICE	device,
		const WORD	vid,
		const WORD	pid,
		const BYTE	power,
		const BYTE	powerMode,
		const WORD	releaseVersion,
		const BYTE	flushBuffers,
		const BYTE	mask
	)

Allows one-time customization of the USB configuration, which includes vendor ID, product ID, power, power mode, release version, and flush buffers setting.Each field can be independently programmed one time each via the mask field.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	vid	is the 2-byte Vendor ID value.
[in]	pid	is the 2-byte Product ID value.
[in]	power	is the 1-byte power value which specifies the current requested by the device IFF the device is configured to be bus powered. See HID_UART_BUS_POWER_MAX.
[in]	powerMode	is the 1-byte Power Mode value to configure the device as bus powered or self powered. See Power Modes.
[in]	releaseVersion	is the 2-byte Major.Minor Release Version value.
[in]	flushBuffers	is the 2-byte Flush Buffers value. See Flush Buffers Bitmasks.
[in]	mask	is the 1-byte bitmask value specifying which fields to customize. See USB Config Bitmasks.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– power and/or powerMode is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_StartBreak()

HID_UART_STATUS HidUart_StartBreak	(	const HID_UART_DEVICE	device,
		const BYTE	DurationInMilliseconds
	)

Causes the device to transmit a line break, holding the TX pin low, for the specified duration in milliseconds.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	DurationInMilliseconds	is the 1-byte length of time in milliseconds to transmit the line break (1-125 ms).

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– DurationInMilliseconds is an unexpected value
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_StopBreak()

HID_UART_STATUS HidUart_StopBreak ( const HID_UART_DEVICE device )

Stops the device from transmitting a line break.

Parameters

[in] device is the Device object pointer as returned by HidUart_Open().

Note: This function successfully no-ops if the device is not transmitting a line break. See HidUart_StartBreak().

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

◆ HidUart_Write()

HID_UART_STATUS HidUart_Write	(	const HID_UART_DEVICE	device,
		BYTE *	buffer,
		const DWORD	numBytesToWrite,
		DWORD *	pNumBytesWritten
	)

Write the specified number of bytes from the supplied buffer to the device. This function returns synchronously after writing the requested number of bytes or after the timeout duration has elapsed. Read and write timeouts can be set using HidUart_SetTimeouts().

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	buffer	- Address of a buffer to be sent to the device.
[in]	numBytesToWrite	of bytes to write to the device (HID_UART_MIN_WRITE_SIZE / 1 - HID_UART_MAX_WRITE_SIZE / 4096 bytes) less than or equal to the size of buffer.
[out]	pNumBytesWritten	points to a buffer into which the number of bytes actually written to the device will be written.

Note: HidUart_Write() returns HID_UART_WRITE_TIMED_OUT if the number of bytes written is less than the number of bytes requested. Data is broken down into HID interrupt reports between 1 - 63 bytes in size and transmitted. Each report will be given a specific amount of time to complete. This report timeout is determined by writeTimeout in HidUart_SetTimeouts(). Each interrupt report is given the max timeout to complete because a timeout at the interrupt report level is considered an unrecoverable error (the IO is canceled in an unknown state). If the HID set interrupt report times out, HidUart_Write() returns HID_UART_WRITE_ERROR. The HidUart_Write() timeout may take up to twice as long as the timeout specified to allow each interrupt report to complete.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_INVALID_PARAMETER	– buffer and/or pNumBytesWritten is an unexpected value
HID_UART_INVALID_REQUEST_LENGTH	– numBytesToWrite must be in the range (HID_UART_MIN_WRITE_SIZE / 1 - HID_UART_MAX_WRITE_SIZE / 4096)
HID_UART_WRITE_ERROR	– tbd
HID_UART_WRITE_TIMED_OUT	– the number of bytes written is less than the number of bytes requested. See note above for more information.

◆ HidUart_WriteLatch()

HID_UART_STATUS HidUart_WriteLatch	(	const HID_UART_DEVICE	device,
		const WORD	LatchValue,
		const WORD	LatchMask
	)

Sets the current port latch value to the device.

Parameters

[in]	device	is the Device object pointer as returned by HidUart_Open().
[in]	LatchValue	a 2-byte port latch value to write to the device. see Pin Config Mode Array indices.
[in]	LatchMask	is a 2-byte bitmask which determines which bits of the port latch value to change (Change = 1, Leave = 0).

The port latch value (Logic High = 1, Logic Low = 0) used to set the values for GPIO pins or flow control pins that are configured as outputs.This function will not affect any pins that are not configured as outputs.

See Pin Config Mode Array indices Port Latch Pin Definition for more information on configuring GPIO and flow control pins. Bits 9 and 15 of LatchValue and LatchMask are ignored. Pins TX, RX, Suspend, and /Suspend cannot be written to using this function.

Returns: Returns HID_UART_SUCCESS on success, or another HID_UART_STATUS Return value if there is an error.

Return values

HID_UART_SUCCESS	– success
HID_UART_INVALID_DEVICE_OBJECT	– device is not a valid, recognized Device object
HID_UART_DEVICE_IO_FAILED	– failed, the device failed to respond to I/O in any expected manner

Modules

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ HID_TO_UART_API

◆ HID_UART_BUS_POWER_MAX

◆ HID_UART_DEVICE_STRLEN

◆ WINAPI

Typedef Documentation

◆ HID_UART_DEVICE

◆ HID_UART_DEVICE_STR

◆ HID_UART_MFG_STR

◆ HID_UART_PRODUCT_STR

◆ HID_UART_SERIAL_STR

◆ PHID_UART_STATUS

◆ U16

◆ U8

Enumeration Type Documentation

◆ HID_UART_STATUS

Function Documentation

◆ HidUart_CancelIo()

◆ HidUart_Close()

◆ HidUart_FlushBuffers()

◆ HidUart_GetAttributes()

◆ HidUart_GetHidGuid()

◆ HidUart_GetHidLibraryVersion()

◆ HidUart_GetIndexedString()

◆ HidUart_GetLibraryVersion()

◆ HidUart_GetLock()

◆ HidUart_GetManufacturingString()

◆ HidUart_GetNumDevices()

◆ HidUart_GetOpenedAttributes()

◆ HidUart_GetOpenedIndexedString()

◆ HidUart_GetOpenedString()

◆ HidUart_GetPartNumber()

◆ HidUart_GetProductString()

◆ HidUart_GetSerialString()

◆ HidUart_GetString()

◆ HidUart_GetTimeouts()

◆ HidUart_GetUartConfig()

◆ HidUart_GetUartEnable()

◆ HidUart_GetUartStatus()

◆ HidUart_GetUsbConfig()

◆ HidUart_IsOpened()

◆ HidUart_Open()

◆ HidUart_Read()

◆ HidUart_ReadLatch()

◆ HidUart_Reset()

◆ HidUart_SetLock()

◆ HidUart_SetManufacturingString()

◆ HidUart_SetProductString()

◆ HidUart_SetSerialString()

◆ HidUart_SetTimeouts()

◆ HidUart_SetUartConfig()

◆ HidUart_SetUartEnable()

◆ HidUart_SetUsbConfig()

◆ HidUart_StartBreak()

◆ HidUart_StopBreak()

◆ HidUart_Write()

◆ HidUart_WriteLatch()