Silicon Labs Host Libraries
CP2112 SMBus over HID interface Library

Modules

 HID_SMBUS_STATUS Return Codes definitions
 
 HID_SMBUS_S0 definitions
 
 HID_SMBUS_S1_BUSY definitions
 
 HID_SMBUS_S1_ERROR definitions
 
 SMbus Configuration Limits definitions
 
 Read/Write Limits definitions
 
 GPIO Pin Direction Bit Value definitions
 
 GPIO Pin Mode Bit Value definitions
 
 GPIO Function Bitmask definitions
 
 GPIO Function Bit Value definitions
 
 GPIO Pin Bitmask definitions
 
 Field Lock Bit Values definitions
 
 Power Modes definitions
 
 USB Config Bitmasks definitions
 
 USB Config Bit Values definitions
 
 String Lengths definitions
 

Macros

#define HID_TO_SMBUS_API
 HID to smbus api definition. More...
 
#define WINAPI
 Windows api definition. More...
 
#define HID_SMBUS_DEVICE_STRLEN   260
 HID SMBus device string length. More...
 
#define HID_SMBUS_PART_CP2112   CP210x_PARTNUM_CP2112
 HID SMBus part number cp2112. More...
 
#define HID_SMBUS_BUS_POWER_MAX   0xFA
 maximum power of 500mA, represented as a milliamps/2, I.e. 250 IFF bus-powered More...
 

Typedefs

typedef int HID_SMBUS_STATUS
 HID SMBus status. More...
 
typedef BYTE HID_SMBUS_S0
 HID_SMBUS_TRANSFER_S0. More...
 
typedef BYTE HID_SMBUS_S1
 HID_SMBUS_TRANSFER_S1. More...
 
typedef enum _HID_SMBUS_GETSTRING * PHID_SMBUS_GETSTRING
 Product String Types pointer. More...
 
typedef char HID_SMBUS_DEVICE_STR[260]
 HID_SMBUS_DEVICE_STR. More...
 
typedef enum _HID_SMBUS_LOCKBITS * PHID_SMBUS_LOCKBITS
 User-Customizable Field Lock Bitmasks pointer. More...
 
typedef char HID_SMBUS_CP2112_MFG_STR[30]
 HID_SMBUS_MFG_STR. More...
 
typedef char HID_SMBUS_CP2112_PRODUCT_STR[30]
 HID_SMBUS_PRODUCT_STR. More...
 
typedef char HID_SMBUS_CP2112_SERIAL_STR[30]
 HID_SMBUS_SERIAL_STR. More...
 
typedef void * HID_SMBUS_DEVICE
 HID_SMBUS_DEVICE. More...
 

Enumerations

enum  HID_SMBUS_GETSTRING {
  HID_SMBUS_GET_VID_STR = 0x01, HID_SMBUS_GET_PID_STR = 0x02, HID_SMBUS_GET_PATH_STR = 0x03, HID_SMBUS_GET_SERIAL_STR = 0x04,
  HID_SMBUS_GET_MANUFACTURER_STR = 0x05, HID_SMBUS_GET_PRODUCT_STR = 0x06
}
 
enum  HID_SMBUS_LOCKBITS {
  HID_SMBUS_LOCK_VID = ((BYTE)(0xFF & 0x01)), HID_SMBUS_LOCK_PID = ((BYTE)(0xFF & 0x02)), HID_SMBUS_LOCK_POWER = ((BYTE)(0xFF & 0x04)), HID_SMBUS_LOCK_POWER_MODE = ((BYTE)(0xFF & 0x08)),
  HID_SMBUS_LOCK_RELEASE_VERSION = ((BYTE)(0xFF & 0x10)), HID_SMBUS_LOCK_MFG_STR = ((BYTE)(0xFF & 0x20)), HID_SMBUS_LOCK_PRODUCT_STR = ((BYTE)(0xFF & 0x40)), HID_SMBUS_LOCK_SERIAL_STR = ((BYTE)(0xFF & 0x80))
}
 

Functions

HID_SMBUS_STATUS HidSmbus_GetNumDevices (DWORD *lpdwNumDevices, const WORD vid, const WORD pid)
 Determines the number of devices connected to the system with matching VID/PID. More...
 
HID_SMBUS_STATUS HidSmbus_GetString (const DWORD deviceNum, const WORD vid, const WORD pid, char *deviceString, const HID_SMBUS_GETSTRING 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_SMBUS_STATUS HidSmbus_GetOpenedString (const HID_SMBUS_DEVICE device, char *deviceString, const HID_SMBUS_GETSTRING 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_SMBUS_STATUS HidSmbus_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_SMBUS_STATUS HidSmbus_GetOpenedIndexedString (const HID_SMBUS_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_SMBUS_STATUS HidSmbus_GetAttributes (const DWORD deviceNum, const WORD vid, const WORD pid, WORD *deviceVid, WORD *devicePid, WORD *deviceReleaseNumber)
 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_SMBUS_STATUS HidSmbus_GetOpenedAttributes (const HID_SMBUS_DEVICE device, WORD *deviceVid, WORD *devicePid, WORD *deviceReleaseNumber)
 This function returns the device vendor ID, product ID, and device release number for the opened device. More...
 
HID_SMBUS_STATUS HidSmbus_Open (HID_SMBUS_DEVICE *pdevice, const DWORD deviceNum, const WORD vid, const WORD pid)
 Opens a device using a device number between 0 and HidSmbus_GetNumDevices() - 1, enables the UART, and returns a device object pointer which will be used for subsequent accesses. More...
 
HID_SMBUS_STATUS HidSmbus_Close (const HID_SMBUS_DEVICE device)
 Closes an opened device using the device object pointer provided by HidUart_Open(). More...
 
HID_SMBUS_STATUS HidSmbus_IsOpened (const HID_SMBUS_DEVICE device, BOOL *bIsOpened)
 Returns the device opened status. More...
 
HID_SMBUS_STATUS HidSmbus_ReadRequest (const HID_SMBUS_DEVICE device, const BYTE slaveAddress, const WORD numBytesToRead)
 intiates a read transfer to the specified slave device address. More...
 
HID_SMBUS_STATUS HidSmbus_AddressReadRequest (const HID_SMBUS_DEVICE device, const BYTE slaveAddress, const WORD numBytesToRead, const BYTE targetAddressSize, BYTE targetAddress[16])
 intiates a read transfer to the specified slave device address and specifies the address to read from on the device. Read and write timeouts as well as transfer retries can be set using HidSmbus_SetSmbusConfig() More...
 
HID_SMBUS_STATUS HidSmbus_ForceReadResponse (const HID_SMBUS_DEVICE device, const WORD numBytesToRead)
 cause the device to send a read response to the host after a read transfer has been issued. More...
 
HID_SMBUS_STATUS HidSmbus_GetReadResponse (const HID_SMBUS_DEVICE device, HID_SMBUS_S0 *status, BYTE *buffer, const BYTE bufferSize, BYTE *numBytesRead)
 returns the read response to a read request. Read and write timeouts as well as transfer retries can be set using HidSmbus_SetSmbusConfig() More...
 
HID_SMBUS_STATUS HidSmbus_WriteRequest (const HID_SMBUS_DEVICE device, const BYTE slaveAddress, BYTE *buffer, const BYTE numBytesToWrite)
 writes the specified number of bytes from the supplied buffer to the specified slave device and returns immediately after sending the request to the CP2112. More...
 
HID_SMBUS_STATUS HidSmbus_TransferStatusRequest (const HID_SMBUS_DEVICE device)
 requests the status of the current read or write transfer. More...
 
HID_SMBUS_STATUS HidSmbus_GetTransferStatusResponse (const HID_SMBUS_DEVICE device, HID_SMBUS_S0 *status, HID_SMBUS_S1 *detailedStatus, WORD *numRetries, WORD *bytesRead)
 returns the status of the current read or write transfer. More...
 
HID_SMBUS_STATUS HidSmbus_CancelTransfer (const HID_SMBUS_DEVICE device)
 cancels the current read or write transfer. More...
 
HID_SMBUS_STATUS HidSmbus_CancelIo (const HID_SMBUS_DEVICE device)
 This function cancels any pending HID reads and writes (Windows Only). More...
 
HID_SMBUS_STATUS HidSmbus_SetTimeouts (const HID_SMBUS_DEVICE device, const DWORD responseTimeout)
 Sets the response timeouts. More...
 
HID_SMBUS_STATUS HidSmbus_GetTimeouts (const HID_SMBUS_DEVICE device, DWORD *responseTimeout)
 returns the current response timeouts specified in milliseconds. More...
 
HID_SMBUS_STATUS HidSmbus_SetSmbusConfig (const HID_SMBUS_DEVICE device, const DWORD bitRate, const BYTE address, const BOOL autoReadRespond, const WORD writeTimeout, const WORD readTimeout, const BOOL sclLowTimeout, const WORD transferRetries)
 sets the SMBus bit rate, address, and transfer settings such as timeouts and retries. More...
 
HID_SMBUS_STATUS HidSmbus_GetSmbusConfig (const HID_SMBUS_DEVICE device, DWORD *bitRate, BYTE *address, BOOL *autoReadRespond, WORD *writeTimeout, WORD *readTimeout, BOOL *sclLowtimeout, WORD *transferRetries)
 gets the SMBus bit rate, address, and transfer settings such as timeouts and retries. More...
 
HID_SMBUS_STATUS HidSmbus_Reset (const HID_SMBUS_DEVICE device)
 initiates a full device reset. All configuration settings will be reset to their default values after the device re-enumerates. More...
 
HID_SMBUS_STATUS HidSmbus_SetGpioConfig (const HID_SMBUS_DEVICE device, const BYTE direction, const BYTE mode, const BYTE function, const BYTE clkDiv)
 configures the GPIO pin's directions and modes. More...
 
HID_SMBUS_STATUS HidSmbus_GetGpioConfig (const HID_SMBUS_DEVICE device, BYTE *direction, BYTE *mode, BYTE *function, BYTE *clkDiv)
 returns the GPIO pin's directions and modes. More...
 
HID_SMBUS_STATUS HidSmbus_ReadLatch (const HID_SMBUS_DEVICE device, BYTE *latchValue)
 returns the current GPIO latch value. More...
 
HID_SMBUS_STATUS HidSmbus_WriteLatch (const HID_SMBUS_DEVICE device, const BYTE latchValue, const BYTE latchMask)
 sets the current GPIO latch value for the specified bits. More...
 
HID_SMBUS_STATUS HidSmbus_GetPartNumber (const HID_SMBUS_DEVICE device, BYTE *partNumber, BYTE *version)
 retrieves the part number and version of the CP2112 device. More...
 
HID_SMBUS_STATUS HidSmbus_GetLibraryVersion (BYTE *major, BYTE *minor, BOOL *bIsRelease)
 Reads and returns the HID USB-to-SMBus Interface Library version. More...
 
HID_SMBUS_STATUS HidSmbus_GetHidLibraryVersion (BYTE *major, BYTE *minor, BOOL *bIsRelease)
 Reads and returns the version of the HID Device Interface Library that is currently in use. More...
 
HID_SMBUS_STATUS HidSmbus_GetHidGuid (void *pHIDGuid)
 Return the GUID for HIDClass devices ("return the HID GUID") (Windows only) More...
 
HID_SMBUS_STATUS HidSmbus_SetLock (const HID_SMBUS_DEVICE device, const BYTE lock)
 permanently locks/disables device customization. More...
 
HID_SMBUS_STATUS HidSmbus_GetLock (const HID_SMBUS_DEVICE device, BYTE *lock)
 Get and return the device customization lock status. More...
 
HID_SMBUS_STATUS HidSmbus_SetUsbConfig (const HID_SMBUS_DEVICE device, const WORD vid, const WORD pid, const BYTE power, const BYTE powerMode, const WORD releaseVersion, const BYTE mask)
 This function allows one-time customization of the USB configuration, which includes vendor ID, product ID, power, power mode, and release version settings.Each field can be independently programmed one time via the mask field. More...
 
HID_SMBUS_STATUS HidSmbus_GetUsbConfig (const HID_SMBUS_DEVICE device, WORD *vid, WORD *pid, BYTE *power, BYTE *powerMode, WORD *releaseVersion)
 retrieves USB configuration, which includes vendor ID, product ID, power, power mode, release version, and flush buffers settings. More...
 
HID_SMBUS_STATUS HidSmbus_SetManufacturingString (const HID_SMBUS_DEVICE device, char *manufacturingString, const BYTE strlen)
 Allows one-time customization of the USB manufacturing string. More...
 
HID_SMBUS_STATUS HidSmbus_GetManufacturingString (const HID_SMBUS_DEVICE device, char *manufacturingString, BYTE *strlen)
 retrieves the USB manufacturing string. More...
 
HID_SMBUS_STATUS HidSmbus_SetProductString (const HID_SMBUS_DEVICE device, char *productString, const BYTE strlen)
 allows one-time customization of the USB product string. More...
 
HID_SMBUS_STATUS HidSmbus_GetProductString (const HID_SMBUS_DEVICE device, char *productString, BYTE *strlen)
 retrieves the USB product string. More...
 
HID_SMBUS_STATUS HidSmbus_SetSerialString (const HID_SMBUS_DEVICE device, char *serialString, const BYTE strlen)
 allows one-time customization of the USB serial string. More...
 
HID_SMBUS_STATUS HidSmbus_GetSerialString (const HID_SMBUS_DEVICE device, char *serialString, BYTE *strlen)
 retrieves the USB product string. More...
 

Detailed Description

Macro Definition Documentation

◆ HID_SMBUS_BUS_POWER_MAX

#define HID_SMBUS_BUS_POWER_MAX   0xFA

maximum power of 500mA, represented as a milliamps/2, I.e. 250 IFF bus-powered

◆ HID_SMBUS_DEVICE_STRLEN

#define HID_SMBUS_DEVICE_STRLEN   260

HID SMBus device string length.

◆ HID_SMBUS_PART_CP2112

HID_SMBUS_PART_CP2112   CP210x_PARTNUM_CP2112

HID SMBus part number cp2112.

CP2112 Part Numbers.

◆ HID_TO_SMBUS_API

#define HID_TO_SMBUS_API

HID to smbus api definition.

◆ WINAPI

#define WINAPI

Windows api definition.

Typedef Documentation

◆ HID_SMBUS_CP2112_MFG_STR

HID_SMBUS_CP2112_MFG_STR

HID_SMBUS_MFG_STR.

◆ HID_SMBUS_CP2112_PRODUCT_STR

HID_SMBUS_CP2112_PRODUCT_STR

HID_SMBUS_PRODUCT_STR.

◆ HID_SMBUS_CP2112_SERIAL_STR

HID_SMBUS_CP2112_SERIAL_STR

HID_SMBUS_SERIAL_STR.

◆ HID_SMBUS_DEVICE

HID_SMBUS_DEVICE.

◆ HID_SMBUS_DEVICE_STR

HID_SMBUS_DEVICE_STR

HID_SMBUS_DEVICE_STR.

◆ HID_SMBUS_S0

HID_SMBUS_TRANSFER_S0.

◆ HID_SMBUS_S1

HID_SMBUS_TRANSFER_S1.

◆ HID_SMBUS_STATUS

HID SMBus status.

◆ PHID_SMBUS_GETSTRING

Product String Types pointer.

◆ PHID_SMBUS_LOCKBITS

User-Customizable Field Lock Bitmasks pointer.

Enumeration Type Documentation

◆ HID_SMBUS_GETSTRING

Enumerator
HID_SMBUS_GET_VID_STR 

Vendor ID string.

HID_SMBUS_GET_PID_STR 

Product ID string.

HID_SMBUS_GET_PATH_STR 

Path string.

HID_SMBUS_GET_SERIAL_STR 

Serial Number string.

HID_SMBUS_GET_MANUFACTURER_STR 

Manufacturer string.

HID_SMBUS_GET_PRODUCT_STR 

Product string.

◆ HID_SMBUS_LOCKBITS

HidSmbus_SetLock() and HidSmbus_GetLock() options values

Enumerator
HID_SMBUS_LOCK_VID 

VID.

HID_SMBUS_LOCK_PID 

PID.

HID_SMBUS_LOCK_POWER 

Power.

HID_SMBUS_LOCK_POWER_MODE 

Power Mode.

HID_SMBUS_LOCK_RELEASE_VERSION 

Release Version.

HID_SMBUS_LOCK_MFG_STR 

Manufacturing String.

HID_SMBUS_LOCK_PRODUCT_STR 

Product String.

HID_SMBUS_LOCK_SERIAL_STR 

Serial String.

Function Documentation

◆ HidSmbus_AddressReadRequest()

HID_SMBUS_STATUS HidSmbus_AddressReadRequest ( const HID_SMBUS_DEVICE  device,
const BYTE  slaveAddress,
const WORD  numBytesToRead,
const BYTE  targetAddressSize,
BYTE  targetAddress[16] 
)

intiates a read transfer to the specified slave device address and specifies the address to read from on the device. Read and write timeouts as well as transfer retries can be set using HidSmbus_SetSmbusConfig()

HidSmbus_AddressReadRequest() initiates a read transfer. SMBus is a half-duplex bus which means that only one read, address read, or write transfer can be active at a time. The device will attempt to read up to transferRetries number of times and for readTimeout milliseconds before timing out. See HidSmbus_SetSmbusConfig() for more information on configuring read timeouts. If the autoReadRespond setting is enabled, then call HidSmbus_GetReadResponse() to return the results of the read transfer. The device will transmit the target address on the bus after the slave device has acknowledged its address. This function is designed to read from EEPROMs with an SMBus interface.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]slaveAddressthe address of the slave device to read from. This value must be between 0x02-0xFE. The least significant bit is the read / write bit for the SMBus transaction and must be 0.
[in]numBytesToReadis the number of bytes to read from the device (1-512).
[in]targetAddressSizeis the size of the target address in bytes (1-16).
[in]targetAddressis the address to read from the slave device.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– slaveAddress and/or numBytesToRead and/or targetAddressSize and/or targetAddress is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_CancelIo()

HID_SMBUS_STATUS HidSmbus_CancelIo ( const HID_SMBUS_DEVICE  device)

This function cancels any pending HID reads and writes (Windows Only).

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_CancelTransfer()

HID_SMBUS_STATUS HidSmbus_CancelTransfer ( const HID_SMBUS_DEVICE  device)

cancels the current read or write transfer.

This function will clear any read responses received.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_Close()

HID_SMBUS_STATUS HidSmbus_Close ( const HID_SMBUS_DEVICE  device)

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

Parameters
[in]deviceis the Device object pointer as returned by HidSmbus_Open().
Note
The device parameter is invalid after calling HidSmbus_Close(). Set device to NULL after calling HidSmbus_Close().
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– Success
HID_SMBUS_INVALID_DEVICE_OBJECT– Device is not a valid, recognized Device object
HID_SMBUS_INVALID_HANDLE– Failed, the device specified by device does not have a valid handle
HID_SMBUS_DEVICE_ACCESS_ERROR– Tbd

◆ HidSmbus_ForceReadResponse()

HID_SMBUS_STATUS HidSmbus_ForceReadResponse ( const HID_SMBUS_DEVICE  device,
const WORD  numBytesToRead 
)

cause the device to send a read response to the host after a read transfer has been issued.

HidSmbus_ForceReadResponse() should only be called if autoReadRespond is disabled using HidSmbus_SetSmbusConfig(). This allows the user to read data in a polled mode. Call HidSmbus_ReadRequest() or HidSmbus_AddressReadRequest() first. Next, call HidSmbus_TransferStatusRequest() and HidSmbus_GetTransferStatusResponse() to check if the device has received data. Next, call HidSmbus_ForceReadResponse(). Finally, call HidSmbus_GetReadResponse() repeatedly until all read data is returned.

Note
Typically, this procedure is not necessary as users should enable the autoReadRespond setting.
Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]numBytesToReadis the number of bytes to read from the device (1-512).
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– numBytesToRead is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetAttributes()

HID_SMBUS_STATUS HidSmbus_GetAttributes ( const DWORD  deviceNum,
const WORD  vid,
const WORD  pid,
WORD *  deviceVid,
WORD *  devicePid,
WORD *  deviceReleaseNumber 
)

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]deviceNumIndex of the device for which the string is desired.
[in]vidis the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]pidis 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]deviceReleaseNumberPoints 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_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– – deviceVid, devicePid and/or pDeviceReleaseNumber is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetGpioConfig()

HID_SMBUS_STATUS HidSmbus_GetGpioConfig ( const HID_SMBUS_DEVICE  device,
BYTE direction,
BYTE mode,
BYTE function,
BYTE clkDiv 
)

returns the GPIO pin's directions and modes.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]directionreturns the 1-byte bitmask that specifies each GPIO pin's direction. See GPIO Pin Direction Bit Value definitions.
[out]modereturns the 1-byte bitmask that specifies each GPIO pin's mode. See GPIO Pin Mode Bit Value definitions.
[out]functionreturns the 1-byte bitmask that specifies the special behavior of GPIO.0, GPIO.1, and GPIO.7. See GPIO Function Bitmask definitions.
[out]clkDivreturns the 1-byte clock output divider value used for GPIO.7 when configured in clock output mode. The frequency is equal to 48 MHz / (2 x clkDiv) when clkDiv is between 1 and 255 and equal to 48 MHz when clkDiv is 0.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– direction and/or mode and/or function and/or clkDiv is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetHidGuid()

HID_SMBUS_STATUS HidSmbus_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]pHIDGuidpoints 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.
Deprecated:
please use HidUart_GetHidGuidSafe()
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– pHIDGuid is an unexpected value

◆ HidSmbus_GetHidLibraryVersion()

HID_SMBUS_STATUS HidSmbus_GetHidLibraryVersion ( BYTE major,
BYTE minor,
BOOL *  bIsRelease 
)

Reads and returns the version of the HID Device Interface Library that is currently in use.

Parameters
majorpoints at a byte-sized buffer into which the major number part of the Firmware Version will be written
minorpoints at a byte-sized buffer into which the minor number part of the Firmware Version will be written
bIsReleasepoints at a BOOL-sized buffer into which a True/False indication of whether the Firmware is a Release-build or not (Debug-build) will be written
Returns
Returns HID_SMBUS_SUCCESS on success, another HID_SMBUS_STATUS Return Codes definitions if there is an error:
Return values
HID_SMBUS_INVALID_PARAMETER– major or minor or bIsRelease is an unexpected value
HID_SMBUS_DEVICE_ACCESS_ERROR– the device failed to respond to I/O in any expected manner

◆ HidSmbus_GetIndexedString()

HID_SMBUS_STATUS HidSmbus_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]deviceNumIndex of the device for which the string is desired.
[in]vidis the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]pidis 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 HID_SMBUS_DEVICE_STR 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_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– deviceString was not specified, and/or options is an unexpected value
HID_SMBUS_DEVICE_NOT_FOUND– the specified device was not found
HID_SMBUS_DEVICE_ALREADY_OPENED– the specified device is already (exclusively) opened
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetLibraryVersion()

HID_SMBUS_STATUS HidSmbus_GetLibraryVersion ( BYTE major,
BYTE minor,
BOOL *  bIsRelease 
)

Reads and returns the HID USB-to-SMBus Interface Library version.

Parameters
[out]majorpoints at a byte-sized buffer into which the major number part of the DLL Version will be written
[out]minorpoints at a byte-sized buffer into which the minor number part of the DLL Version will be written
[out]bIsReleasepoints at a BOOL-sized buffer into which a True/False indication of whether the DLL is a Release-build or not (Debug-build) will be written
Returns
Returns HID_SMBUS_SUCCESS on success, another HID_SMBUS_STATUS Return Codes definitions if there is an error:
Return values
HID_SMBUS_INVALID_PARAMETER– major or minor or bIsRelease is an unexpected value

◆ HidSmbus_GetLock()

HID_SMBUS_STATUS HidSmbus_GetLock ( const HID_SMBUS_DEVICE  device,
BYTE lock 
)

Get and return the device customization lock status.

Parameters
[in]deviceis an open handle to the device as returned from HidSmbus_Open()
[out]lockpoints at a 1-byte buffer into which the HID_SMBUS_LOCKBITS bitmask specifying which fields are locked will be copied and returned
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– lock was not specified, and/or is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetManufacturingString()

HID_SMBUS_STATUS HidSmbus_GetManufacturingString ( const HID_SMBUS_DEVICE  device,
char *  manufacturingString,
BYTE strlen 
)

retrieves the USB manufacturing string.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]manufacturingStringis a variable of type HID_SMBUS_CP2112_MFG_STR, a 30-byte character buffer that will contain the ASCII manufacturing string.
[out]strlenreturns the length of the string in bytes.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– manufacturingString and/or strlen is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetNumDevices()

HID_SMBUS_STATUS HidSmbus_GetNumDevices ( DWORD *  lpdwNumDevices,
const WORD  vid,
const WORD  pid 
)

Determines the number of devices connected to the system with matching VID/PID.

Parameters
[out]lpdwNumDevicesa pointer to a DWORD/4-byte location to hold the returned device count
[in]vidis the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]pidis 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_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– lpdwNumDevices was not specified, or is an unexpected value

◆ HidSmbus_GetOpenedAttributes()

HID_SMBUS_STATUS HidSmbus_GetOpenedAttributes ( const HID_SMBUS_DEVICE  device,
WORD *  deviceVid,
WORD *  devicePid,
WORD *  deviceReleaseNumber 
)

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

Parameters
[in]deviceis the Device object pointer as returned by HidSmbus_Open().
[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]deviceReleaseNumberPoints 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_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– deviceString was not specified, and/or options is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetOpenedIndexedString()

HID_SMBUS_STATUS HidSmbus_GetOpenedIndexedString ( const HID_SMBUS_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]deviceis the Device object pointer as returned by HidSmbus_Open().
[in]stringIndex- Specifies the device-specific index of the USB string descriptor to return.
[out]deviceString- Variable of type HID_SMBUS_DEVICE_STR 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_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– deviceString is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetOpenedString()

HID_SMBUS_STATUS HidSmbus_GetOpenedString ( const HID_SMBUS_DEVICE  device,
char *  deviceString,
const HID_SMBUS_GETSTRING  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]deviceis the Device object pointer as returned by HidSmbus_Open().
[out]deviceString- Variable of type HID_SMBUS_DEVICE_STR 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 HID_SMBUS_GETSTRING
Note
BUG: This is an string-UNSAFE function, not defensive against a "too small" buffer provided as the deviceString parameter.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– deviceString was not specified, and/or options is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetPartNumber()

HID_SMBUS_STATUS HidSmbus_GetPartNumber ( const HID_SMBUS_DEVICE  device,
BYTE partNumber,
BYTE version 
)

retrieves the part number and version of the CP2112 device.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]partNumberpoints at a byte-sized buffer into which the Part Number value will be written. See HID_SMBUS_PART_CP2112.
[out]versionpoints at a byte-sized buffer into which the part's Version value will be written
Returns
Returns HID_SMBUS_SUCCESS on success, another HID_SMBUS_STATUS Return Codes definitions if there is an error:
Return values
HID_SMBUS_INVALID_DEVICE_OBJECT– device is invalid
HID_SMBUS_INVALID_PARAMETER– partNumber or version is an unexpected value
HID_SMBUS_DEVICE_IO_FAILED– the device failed to respond to I/O in any expected manner

◆ HidSmbus_GetProductString()

HID_SMBUS_STATUS HidSmbus_GetProductString ( const HID_SMBUS_DEVICE  device,
char *  productString,
BYTE strlen 
)

retrieves the USB product string.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]productStringis a variable of type HID_SMBUS_CP2112_PRODUCT_STR, a 30-byte character buffer that will contain the ASCII product string.
[out]strlenreturns the length of the string in bytes.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– productString and/or strlen is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetReadResponse()

HID_SMBUS_STATUS HidSmbus_GetReadResponse ( const HID_SMBUS_DEVICE  device,
HID_SMBUS_S0 status,
BYTE buffer,
const BYTE  bufferSize,
BYTE numBytesRead 
)

returns the read response to a read request. Read and write timeouts as well as transfer retries can be set using HidSmbus_SetSmbusConfig()

HidSmbus_GetReadResponse() waits for up to readTimeout milliseconds for the device to send a read response interrupt report to the host. This function should be called repeatedly until all read data has been received or an error occurs. Call HidSmbus_ReadRequest() or HidSmbus_AddressReadRequest() followed by HidSmbus_GetReadResponse() to read data when autoReadResponse is enabled using HidSmbus_SetSmbusConfig(). HidSmbus_GetReadResponse() will wait for up to responseTimeout milliseconds before returning HID_SMBUS_READ_TIMED_OUT.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]statuspoints at a 1-byte buffer into which the status of the read request will be copied and returned. See HID_SMBUS_S0 definitions.
[out]buffer- returns up to 61 read data bytes.
[in]bufferSize- is the size of buffer and must be at least 61 bytes.
[out]numBytesRead- returns the number of valid data bytes returned in buffer.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– status and/or buffer and/or buffersize and/or numBytesRead is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetSerialString()

HID_SMBUS_STATUS HidSmbus_GetSerialString ( const HID_SMBUS_DEVICE  device,
char *  serialString,
BYTE strlen 
)

retrieves the USB product string.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]serialStringis a variable of type HID_SMBUS_CP2112_SERIAL_STR, a 30-byte character buffer that will contain the ASCII product string.
[out]strlenreturns the length of the string in bytes.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– serialString and/or strlen is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetSmbusConfig()

HID_SMBUS_STATUS HidSmbus_GetSmbusConfig ( const HID_SMBUS_DEVICE  device,
DWORD *  bitRate,
BYTE address,
BOOL *  autoReadRespond,
WORD *  writeTimeout,
WORD *  readTimeout,
BOOL *  sclLowtimeout,
WORD *  transferRetries 
)

gets the SMBus bit rate, address, and transfer settings such as timeouts and retries.

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

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]bitRatereturns the 4-byte bit rate for SMBus communication. The default is 100 kHz. This value must be non-zero.
[out]addressreturns the 1-byte device's slave address (0x02-0xFE) address. The device will only acknowledge this address. The default is 0x02. The least significant bit is the read/write bit for the SMBus transaction and must be 0.
[out]autoReadRespondreturns the 4-byte boolean value that controls the read response behavior of the device. If enabled, the device will automatically send read response interrupt reports to the device after initiating a read transfer. If disabled, the user must call HidSmbus_ForceReadResponse() before read response interrupt reports will be sent to the host. The default is FALSE(0).
[out]writeTimeoutreturns the 2-byte time limit in milliseconds (0-1000) before the device will automatically cancel a write transfer. A value of 0 indicates an infinite timeout. In this case, a write transfer will wait indefinitely for a write to complete or until HidSmbus_CancelTransfer() is called. The default is 0.
[out]readTimeoutreturns the 2-byte time limit in milliseconds (0 - 1000) before the device will automatically cancel a read transfer. A value of 0 indicates an infinite timeout. In this case, a read transfer will wait indefinitely for a read to complete or until HidSmbus_CancelTransfer() is called. The default is 0.
[out]sclLowtimeoutreturns the 4-byte timeout that will reset the SMBus if the SCL line is held low for more than 25ms. If enabled and an SCL Low Timeout occurs, the status byte of the Transfer Status Response command will be set appropriately. The default is FALSE(0).
[out]transferRetriesreturns the 2-byte number of times to retry (0 - 1000) a failed read or write transfer. A value of 0 indicates an infinite number of retries until the specified read or write timeout has elapsed. The default is 0.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– bitRate and/or address and/or autoReadRespond and/or writeTimeout and/or readTimeout and/or sclLowTimeout and/or transferRetries is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetString()

HID_SMBUS_STATUS HidSmbus_GetString ( const DWORD  deviceNum,
const WORD  vid,
const WORD  pid,
char *  deviceString,
const HID_SMBUS_GETSTRING  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]deviceNumIndex of the device for which the string is desired.
[in]vidis the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]pidis the 2-byte Product ID value, filter device results by this Product ID.
[out]deviceString- Variable of type HID_SMBUS_DEVICE_STR 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 HID_SMBUS_GETSTRING
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.
Intended for use pre- HidSmbus_Open() or post- HidSmbus_Close(). Fails with HID_SMBUS_DEVICE_ALREADY_OPENED otherwise.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– deviceString was not specified, and/or options is an unexpected value
HID_SMBUS_DEVICE_NOT_FOUND– the specified device was not found
HID_SMBUS_DEVICE_ALREADY_OPENED– the specified device is already (exclusively) opened
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetTimeouts()

HID_SMBUS_STATUS HidSmbus_GetTimeouts ( const HID_SMBUS_DEVICE  device,
DWORD *  responseTimeout 
)

returns the current response timeouts specified in milliseconds.

A response timeout value of 0 indicates an infinite timeout.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]responseTimeoutpoints at a 4-byte buffer into which the response timeout will be copied and returned.
Note
Timeouts are maintained for each device but are not persistent across HidSmbus_Open()/HidSmbus_Close().
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– responseTimeout is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetTransferStatusResponse()

HID_SMBUS_STATUS HidSmbus_GetTransferStatusResponse ( const HID_SMBUS_DEVICE  device,
HID_SMBUS_S0 status,
HID_SMBUS_S1 detailedStatus,
WORD *  numRetries,
WORD *  bytesRead 
)

returns the status of the current read or write transfer.

Call HidSmbus_TransferStatusRequest() followed by HidSmbus_GetTransferStatusResponse() to get the status of the current read or write transfer. HidSmbus_GetTransferStatusResponse() will wait for up to responseTimeout milliseconds before returning HID_SMBUS_READ_TIMED_OUT.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]statuspoints at a 1-byte buffer into which the status of the read or write request will be copied and returned. See HID_SMBUS_S0 definitions.
[out]detailedStatuspoints at a 1-byte buffer into which the extended status of the read or write request will be copied and returned. See HID_SMBUS_S1.
[out]numRetriespoints at a 2-byte buffer into which the tbd will be copied and returned.
[out]bytesReadpoints at a 2-byte buffer into which the tbd will be copied and returned.

When status of HID_SMBUS_S0_IDLE is returned, for detailedStatus see TBD. When status of HID_SMBUS_S0_BUSY is returned, for detailedStatus see HID_SMBUS_S1_BUSY definitions. When status of HID_SMBUS_S0_ERROR is returned, for detailedStatus see HID_SMBUS_S1_ERROR definitions.

Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– status and/or detailedStatus and/or numRetries and/or bytesRead is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_GetUsbConfig()

HID_SMBUS_STATUS HidSmbus_GetUsbConfig ( const HID_SMBUS_DEVICE  device,
WORD *  vid,
WORD *  pid,
BYTE power,
BYTE powerMode,
WORD *  releaseVersion 
)

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

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]vidPoints to a 1-byte buffer into which the Vendor ID is written and returned.
[out]pidPoints to a 1-byte buffer into which the Product ID is written and returned.
[out]powerPoints 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_SMBUS_BUS_POWER_MAX.
[out]powerModePoints 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 definitions.
[out]releaseVersionPoints to a 1-byte buffer into which the Major.Minor Release Version value is written and returned.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– vid and/or pid and/or power and/or powerMode and/or releaseVersion is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_IsOpened()

HID_SMBUS_STATUS HidSmbus_IsOpened ( const HID_SMBUS_DEVICE  device,
BOOL *  bIsOpened 
)

Returns the device opened status.

Parameters
[in]deviceis the Device object pointer as returned by HidSmbus_Open().
[out]bIsOpenedPoints to a buffer into which a Boolean flag where TRUE means the device object pointer is valid and the device has been opened using HidSmbus_Open(), and FALSE means it has not will be written
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_DEVICE_OBJECT– device is not a valid, recognized Device object
HID_SMBUS_INVALID_PARAMETER– pbIsOpened is an unexpected value

◆ HidSmbus_Open()

HID_SMBUS_STATUS HidSmbus_Open ( HID_SMBUS_DEVICE pdevice,
const DWORD  deviceNum,
const WORD  vid,
const WORD  pid 
)

Opens a device using a device number between 0 and HidSmbus_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-SMBUS device object for subsequent accesses to the device.
[in]deviceNum- Zero-based device index, between 0 and (HidSmbus_GetNumDevices() - 1).
[in]vidis the 2-byte Vendor ID value, filter device results by this Vendor ID.
[in]pidis 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_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_DEVICE_NOT_FOUND– deviceNum is an unexpected value
HID_SMBUS_DEVICE_ACCESS_ERROR– Could not access device (i.e. already opened?)
HID_SMBUS_DEVICE_NOT_SUPPORTED– Per device's PartNum only support CP2110 and CP2114 devices
HID_SMBUS_INVALID_PARAMETER– pdevice is an unexpected value

◆ HidSmbus_ReadLatch()

HID_SMBUS_STATUS HidSmbus_ReadLatch ( const HID_SMBUS_DEVICE  device,
BYTE latchValue 
)

returns the current GPIO latch value.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[out]latchValuepoints at a buffer into which the current GPIO latch value will be copied and returned

If a pin is configured as an input, then the latchValue bit represents the logical voltage level received on the pin. If a pin is configured as an output, then the latchValue bit represents the logical voltage level driven on the pin.

Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– latchValue is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_ReadRequest()

HID_SMBUS_STATUS HidSmbus_ReadRequest ( const HID_SMBUS_DEVICE  device,
const BYTE  slaveAddress,
const WORD  numBytesToRead 
)

intiates a read transfer to the specified slave device address.

Read and write timeouts as well as transfer retries can be set using HidSmbus_SetSmbusConfig().

HidSmbus_ReadRequest() initiates a read transfer. SMBus is a half-duplex bus, which means that only one read, address read, or write transfer can be active at a time.The device will attempt to read up to transferRetries number of times and for readTimeout milliseconds before timing out. See HidSmbus_SetSmbusConfig() for more information on configuring read timeouts. If the autoReadRespond setting is enabled, then call HidSmbus_GetReadResponse() to return the results of the read transfer.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]slaveAddressthe address of the slave device to read from. This value must be between 0x02-0xFE. The least significant bit is the read / write bit for the SMBus transaction and must be 0.
[in]numBytesToReadis the number of bytes to read from the device (1-512).
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– slaveAddress and/or numBytesToRead is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_Reset()

HID_SMBUS_STATUS HidSmbus_Reset ( const HID_SMBUS_DEVICE  device)

initiates a full device reset. All configuration settings will be reset to their default values after the device re-enumerates.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
Note
Resetting the device will make the device handle stale. Users must close the device using the old handle before proceeding to reconnect to the device. See more information on surprise removal. See HidSmbus_SetSmbusConfig() and HidSmbus_SetGpioConfig() for default configuration settings.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_SetGpioConfig()

HID_SMBUS_STATUS HidSmbus_SetGpioConfig ( const HID_SMBUS_DEVICE  device,
const BYTE  direction,
const BYTE  mode,
const BYTE  function,
const BYTE  clkDiv 
)

configures the GPIO pin's directions and modes.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]directionis the 1-byte bitmask that specifies each GPIO pin's direction. See GPIO Pin Direction Bit Value definitions.
[in]modeis the 1-byte bitmask that specifies each GPIO pin's mode. See GPIO Pin Mode Bit Value definitions.
[in]functionis the 1-byte bitmask that specifies the special behavior of GPIO.0, GPIO.1, and GPIO.7. See GPIO Function Bitmask definitions.
[in]clkDivis the 1-byte clock output divider value used for GPIO.7 when configured in clock output mode. The frequency is equal to 48 MHz / (2 x clkDiv) when clkDiv is between 1 and 255 and equal to 48 MHz when clkDiv is 0.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– direction and/or mode and/or function and/or clkDiv is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_SetLock()

HID_SMBUS_STATUS HidSmbus_SetLock ( const HID_SMBUS_DEVICE  device,
const BYTE  lock 
)

permanently locks/disables device customization.

Parameters
[in]deviceis an open handle to the device as returned from HidSmbus_Open()
[in]lockis a 1-byte bitmask specifying which fields can be customized/programmed and which fields are already customized. See HID_SMBUS_LOCKBITS and Field Lock Bit Values definitions.
Note
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_SMBUS_SUCCESS even though the device was not programmed. Call HidSmbus_GetLock() 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.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– lock was not specified, and/or is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_SetManufacturingString()

HID_SMBUS_STATUS HidSmbus_SetManufacturingString ( const HID_SMBUS_DEVICE  device,
char *  manufacturingString,
const BYTE  strlen 
)

Allows one-time customization of the USB manufacturing string.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]manufacturingStringis a variable of type HID_SMBUS_CP2112_MFG_STR, a 30-byte character buffer containing the ASCII manufacturing string.
[in]strlenis the 1-byte length of manufacturingString in bytes.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– manufacturingString and/or strlen is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_SetProductString()

HID_SMBUS_STATUS HidSmbus_SetProductString ( const HID_SMBUS_DEVICE  device,
char *  productString,
const BYTE  strlen 
)

allows one-time customization of the USB product string.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]productStringis a variable of type HID_SMBUS_CP2112_PRODUCT_STR, a 30-byte character buffer containing the ASCII product string.
[in]strlenis the length of productString in bytes. The maximum string length is 30 bytes.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– productString and/or strlen is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_SetSerialString()

HID_SMBUS_STATUS HidSmbus_SetSerialString ( const HID_SMBUS_DEVICE  device,
char *  serialString,
const BYTE  strlen 
)

allows one-time customization of the USB serial string.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]serialStringis a variable of type HID_SMBUS_CP2112_SERIAL_STR, a 30-byte character buffer containing the ASCII serial string.
[in]strlenis the length of serialString in bytes. The maximum string length is 30 bytes.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– serialString and/or strlen is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_SetSmbusConfig()

HID_SMBUS_STATUS HidSmbus_SetSmbusConfig ( const HID_SMBUS_DEVICE  device,
const DWORD  bitRate,
const BYTE  address,
const BOOL  autoReadRespond,
const WORD  writeTimeout,
const WORD  readTimeout,
const BOOL  sclLowTimeout,
const WORD  transferRetries 
)

sets the SMBus bit rate, address, and transfer settings such as timeouts and retries.

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

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]bitRateis the 4-byte bit rate for SMBus communication. The default is 100 kHz. This value must be non-zero.
[in]addressis the 1-byte device's slave address (0x02-0xFE) address. The device will only acknowledge this address. The default is 0x02. The least significant bit is the read/write bit for the SMBus transaction and must be 0.
[in]autoReadRespondis the 4-byte boolean value that controls the read response behavior of the device. If enabled, the device will automatically send read response interrupt reports to the device after initiating a read transfer. If disabled, the user must call HidSmbus_ForceReadResponse() before read response interrupt reports will be sent to the host. The default is FALSE(0).
[in]writeTimeoutis the 2-byte time limit in milliseconds (0-1000) before the device will automatically cancel a write transfer. A value of 0 indicates an infinite timeout. In this case, a write transfer will wait indefinitely for a write to complete or until HidSmbus_CancelTransfer() is called. The default is 0.
[in]readTimeoutis the 2-byte time limit in milliseconds (0 - 1000) before the device will automatically cancel a read transfer. A value of 0 indicates an infinite timeout. In this case, a read transfer will wait indefinitely for a read to complete or until HidSmbus_CancelTransfer() is called. The default is 0.
[in]sclLowTimeoutis the 4-byte timeout that will reset the SMBus if the SCL line is held low for more than 25ms. If enabled and an SCL Low Timeout occurs, the status byte of the Transfer Status Response command will be set appropriately. The default is FALSE(0).
[in]transferRetriesis the 2-byte number of times to retry (0 - 1000) a failed read or write transfer. A value of 0 indicates an infinite number of retries until the specified read or write timeout has elapsed. The default is 0.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– bitRate and/or address and/or autoReadRespond and/or writeTimeout and/or readTimeout and/or sclLowTimeout and/or transferRetries is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_SetTimeouts()

HID_SMBUS_STATUS HidSmbus_SetTimeouts ( const HID_SMBUS_DEVICE  device,
const DWORD  responseTimeout 
)

Sets the response timeouts.

Response timeouts are used by HidSmbus_GetReadResponse() and HidSmbus_GetTransferStatusResponse(). The default value for response timeouts is 1000ms, but timeouts can be set to wait for any number of milliseconds between 1 and 0xFFFFFFFF. Specifying a response timeout of 0, will wait indefinitely.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]responseTimeoutis the 4-byte response timeout.
Note
If timeouts are set to a large value and no data is received, the application may appear unresponsive. It is recommended to set timeouts appropriately before using the device. Typically, users will want to specify a response timeout that is greater than the read and write timeouts.
Timeouts are maintained for each device but are not persistent across HidSmbus_Open()/HidSmbus_Close().
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_SetUsbConfig()

HID_SMBUS_STATUS HidSmbus_SetUsbConfig ( const HID_SMBUS_DEVICE  device,
const WORD  vid,
const WORD  pid,
const BYTE  power,
const BYTE  powerMode,
const WORD  releaseVersion,
const BYTE  mask 
)

This function allows one-time customization of the USB configuration, which includes vendor ID, product ID, power, power mode, and release version settings.Each field can be independently programmed one time via the mask field.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]vidis the 2-byte Vendor ID value.
[in]pidis the 2-byte Product ID value.
[in]poweris the 1-byte power value which specifies the current requested by the device IFF the device is configured to be bus powered. See HID_SMBUS_BUS_POWER_MAX.
[in]powerModeis the 1-byte Power Mode value to configure the device as bus powered or self powered. See Power Modes definitions.
[in]releaseVersionis the 2-byte user-programmable Major.Minor Release Version value.
[in]maskis the 1-byte bitmask value specifying which fields to customize. See USB Config Bitmasks definitions.
Note
releaseVersion version is not the same as the device release number described in the USB device descriptor.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– power and/or powerMode is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_TransferStatusRequest()

HID_SMBUS_STATUS HidSmbus_TransferStatusRequest ( const HID_SMBUS_DEVICE  device)

requests the status of the current read or write transfer.

Call HidSmbus_TransferStatusRequest() followed by HidSmbus_GetTransferStatusResponse() to get the status of the current read or write transfer.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_WriteLatch()

HID_SMBUS_STATUS HidSmbus_WriteLatch ( const HID_SMBUS_DEVICE  device,
const BYTE  latchValue,
const BYTE  latchMask 
)

sets the current GPIO latch value for the specified bits.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]latchValueis the 1-byte output value to drive on GPIO pins configured as outputs. See GPIO Pin Bitmask definitions.
[in]latchMaskis the 1-byte bitmask specifying which bits to modify.
Note
Only GPIO pins configured as outputs with their corresponding latchMask bits set can be written to.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– deviceString was not specified, and/or options is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd

◆ HidSmbus_WriteRequest()

HID_SMBUS_STATUS HidSmbus_WriteRequest ( const HID_SMBUS_DEVICE  device,
const BYTE  slaveAddress,
BYTE buffer,
const BYTE  numBytesToWrite 
)

writes the specified number of bytes from the supplied buffer to the specified slave device and returns immediately after sending the request to the CP2112.

Read and write timeouts can be set using HidSmbus_SetTimeouts().

Call HidSmbus_TransferStatusRequest() / HidSmbus_GetTransferStatusResponse() to wait for the write transfer to complete before issuing another transfer request. The device waits for up to transferRetries number of retries and writeTimeout number of milliseconds before timing out.

Parameters
[in]deviceis an open handle to the device as returned by HidSmbus_Open().
[in]slaveAddressthe address of the slave device to write to. This value must be between 0x02-0xFE. The least significant bit is the read / write bit for the SMBus transaction and must be 0.
[in]bufferis the address of a buffer to be sent to the device.
[in]numBytesToWriteis the number of bytes to write to the device (1-61). This value must be less than or equal to the size of buffer.
Returns
Returns HID_SMBUS_SUCCESS on success, or another HID_SMBUS_STATUS Return Codes definitions Return value if there is an error.
Return values
HID_SMBUS_SUCCESS– success
HID_SMBUS_INVALID_PARAMETER– slaveAddress and/or buffer and/or numBytesToWrite is an unexpected value
HID_SMBUS_INVALID_DEVICE_OBJECT– the specified device is invalid
HID_SMBUS_DEVICE_ACCESS_ERROR– tbd