TWI Wrapper

Functions which simplify handling of register based twi-slaves. More...

Modules
	Advanced informations

Enumerations
enum	eTwiWrapperError
	Functions for simplified access to register-like TWI devices. More...

Bit-Access Functions
enum eTwiWrapperError	twiWrapper_readBit (uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint8_t *data)
	Read a single bit from an 8-bit device register. More...
enum eTwiWrapperError	twiWrapper_readBits (uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t bitLength, uint8_t *data)
	Read multiple bits from an 8-bit device register. More...
enum eTwiWrapperError	twiWrapper_writeBit (uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint8_t data)
	Write a single bit in an 8-bit device register. More...
enum eTwiWrapperError	twiWrapper_writeBits (uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t bitLength, uint8_t data)
	Write multiple bits in an 8-bit device register. More...

Byte Access Functions
enum eTwiWrapperError	twiWrapper_readByte (uint8_t devAddr, uint8_t regAddr, uint8_t *data)
	Read single byte from an 8-bit device register. More...
enum eTwiWrapperError	twiWrapper_readBytes (uint8_t devAddr, uint8_t regAddr, uint8_t byteCount, uint8_t *data)
	Read multiple bytes from an 8-bit device register. More...
enum eTwiWrapperError	twiWrapper_writeByte (uint8_t devAddr, uint8_t regAddr, uint8_t data)
	Write single byte to an 8-bit device register. More...
enum eTwiWrapperError	twiWrapper_writeBytes (uint8_t devAddr, uint8_t regAddr, uint8_t byteCount, uint8_t *data)
	Write multiple bytes to an 8-bit device register. More...

Detailed Description

Functions which simplify handling of register based twi-slaves.

Enumeration Type Documentation

eTwiWrapperError

enum eTwiWrapperError

Functions for simplified access to register-like TWI devices.

All these functions use the TWI api to directly address one or more register of a single TWI device. Hence, reading or manipulating whole registers or single bits, is done by a single a function call.

Since, the TUC-Bot api may constantly communicate to the driving module or the integrated IMU, all twiWrapper functions need to block this internal communication. Therefore, wrapper functions will wait until the currently ongoing transfer on the twi bus is done and block future transfer. This may take some time. Afterwards the lock will be removed.

Always keep these szenarios in mind:

1. Right after the desired transmission through the TwiWrapper api, the TUC-Bot api might start it's own communication again and the global twi error variable will be cleared.
2. If a wrapper function is called while an other wrapper function is executed (e.g. called through a cyclic function), the newly called function will directly abort. This allows the "old" function to work properly.
3. If the user calls a twi function while any wrapper function is executed (e.g. called through a cyclic function), the behavior of the wrapper function is undefined and most likely erroneous.

Note

Wrapper function will ignore if the TWI is locked for the user. However, locking the TWI will speed up the execution (no additional blocking) and allows to read out possible error values, after execution.

Enumerator
kTwiWrapperErrorNone	constant (0): no error
kTwiWrapperErrorLock	constant (1): TWI is locked by the library
kTwiWrapperErrorBusy	constant (2): TWI is currently used by the TWI-Wrapper
kTwiWrapperErrorTimeOut	constant (3): timeout of the TWI Wrapper see also kTwiWrapperDefaultTimeOut
kTwiWrapperErrorRead	constant (4): internal error during reading see also twi_errorGet()
kTwiWrapperErrorWrite	constant (5): internal error during writing see also twi_errorGet()

Function Documentation

twiWrapper_readBit()

enum eTwiWrapperError twiWrapper_readBit	(	uint8_t	devAddr,
		uint8_t	regAddr,
		uint8_t	bitNum,
		uint8_t *	data
	)

Read a single bit from an 8-bit device register.

Parameters

devAddr	TWI slave device address
regAddr	Register address to read from
bitNum	Bit position to read (0-7)
data	Result of read operation (0xFF if bit was set, otherwise 0x00)

Returns

Status of operation (0 == success, otherwise error-code)

example:

#  byte in register   : 01101001
#  bit numbers        : 76543210
#  wanted bit         :     x
#  ==> bitNum = 3
#  masked bit         :     1
#  -----------------------------
#  ==> data (result)  : 11111111 

twiWrapper_readBits()

enum eTwiWrapperError twiWrapper_readBits	(	uint8_t	devAddr,
		uint8_t	regAddr,
		uint8_t	bitStart,
		uint8_t	bitLength,
		uint8_t *	data
	)

Read multiple bits from an 8-bit device register.

Parameters

devAddr	TWI slave device address
regAddr	Register address to read from
bitStart	First bit position to read (0-7)
bitLength	Number of bits to read (not more than 8)
data	Container for right-aligned value (i.e. '101' read from any bitStart position will equal 0x05)

Returns

Status of operation (0 == success, otherwise error-code)

example:

#  byte in register   : 01101001
#  bit numbers        : 76543210
#  wanted bits        :    xxx
#  ==> bitStart  = 2
#  ==> bitLength = 3
#  masked bits        :    010
#  shifted bits       :      010
#  -----------------------------
#  ==> data (result)  : 00000010 

twiWrapper_readByte()

enum eTwiWrapperError twiWrapper_readByte	(	uint8_t	devAddr,
		uint8_t	regAddr,
		uint8_t *	data
	)

Read single byte from an 8-bit device register.

Parameters

devAddr	TWI slave device address
regAddr	Register address to read from
data	Container for byte value read from device

Returns

Status of operation (0 == success, otherwise error-code)

twiWrapper_readBytes()

enum eTwiWrapperError twiWrapper_readBytes	(	uint8_t	devAddr,
		uint8_t	regAddr,
		uint8_t	byteCount,
		uint8_t *	data
	)

Read multiple bytes from an 8-bit device register.

Parameters

devAddr	TWI slave device address
regAddr	First register address to read from
byteCount	Number of bytes to read
data	Buffer to store read data in

Returns

Status of operation (0 == success, otherwise error-code)

twiWrapper_writeBit()

enum eTwiWrapperError twiWrapper_writeBit	(	uint8_t	devAddr,
		uint8_t	regAddr,
		uint8_t	bitNum,
		uint8_t	data
	)

Write a single bit in an 8-bit device register.

Parameters

devAddr	TWI slave device address
regAddr	Register address to write to
bitNum	Bit position to write (0-7)
data	New bit value to be written (0x00: bit is cleared; otherwise bit is set)

Returns

Status of operation (0 == success, otherwise error-code)

example:

#  byte in register   : 01101001
#  bit numbers        : 76543210
#  wanted bit         :    x
#  ==> bitNum = 4
#  new bit value      :    1
#  -----------------------------
#  ==> data           : 11111111
#  (all non-zero values will also work, e.g. 00000110 

twiWrapper_writeBits()

enum eTwiWrapperError twiWrapper_writeBits	(	uint8_t	devAddr,
		uint8_t	regAddr,
		uint8_t	bitStart,
		uint8_t	bitLength,
		uint8_t	data
	)

Write multiple bits in an 8-bit device register.

Parameters

devAddr	TWI slave device address
regAddr	Register address to write to
bitStart	First bit position to write (0-7)
bitLength	Number of bits to write (not more than 8)
data	Right-aligned value to write

Returns

Status of operation (0 == success, otherwise error-code)

example:

#  byte in register   : 01101001
#  bit numbers        : 76543210
#  wanted bits        :    xxx
#  ==> bitStart  = 2
#  ==> bitLength = 3
#  new bit values     :    101
#  shifted bits       :      101
#  -----------------------------
#  ==> data           : 00000101 

twiWrapper_writeByte()

enum eTwiWrapperError twiWrapper_writeByte	(	uint8_t	devAddr,
		uint8_t	regAddr,
		uint8_t	data
	)

Write single byte to an 8-bit device register.

Parameters

devAddr	TWI slave device address
regAddr	Register address to write to
data	New byte value to write

Returns

Status of operation (0 == success, otherwise error-code)

twiWrapper_writeBytes()

enum eTwiWrapperError twiWrapper_writeBytes	(	uint8_t	devAddr,
		uint8_t	regAddr,
		uint8_t	byteCount,
		uint8_t *	data
	)

Write multiple bytes to an 8-bit device register.

Parameters

devAddr	TWI slave device address
regAddr	First register address to write to
byteCount	Number of bytes to write
data	Buffer to copy new data from

Returns

Status of operation (0 == success, otherwise error-code)