-
Notifications
You must be signed in to change notification settings - Fork 4
XWire 2 wire library
For maximum compatibility, the XWire library retains the same names and API as the original 'Wire' library, with the exception of the constructor. You must pass the register address of the appropriate TWI interface as a 'TWI_t *', the only parameter to the constructor, as follows:
TwoWire XWire(&(TWI_DEFAULT));
Otherwise, it's identical to the ATMega implementation for Arduino's 'Wire' library.
The following is a list of low-level 'TWI' API functions that are supported:
void twi_init(TWI_t *pTWI);
void twi_shutdown(TWI_t *pTWI);
void twi_setAddress(TWI_t *pTWI, uint8_t addr);
uint8_t twi_readFrom(TWI_t *pTWI, uint8_t addr, uint8_t *pBuf,
uint8_t cbBuf, uint8_t fStop, uint16_t wTimeout);
uint8_t twi_writeTo(TWI_t *pTWI, uint8_t addr, const uint8_t *pBuf,
uint8_t cbBuf, uint8_t fWait, uint8_t fStop);
uint8_t twi_transmit(TWI_t *pTWI, const uint8_t *pBuf, uint8_t cbBuf);
void twi_attachSlaveRxEvent(TWI_t *pTWI,
void (*cbRX)(TWI_t *pTWI, void *pCtxt,
const uint8_t *pBuf, int cbBuf),
void *pCtxt0 );
void twi_attachSlaveTxEvent(TWI_t *pTWI,
void (*cbTX)(TWI_t *pTWI, void *pCtxt),
void *pCtxt0 );
void twi_stop(TWI_t *pTWI);
Note that parameters differ from Arduino 'reference' implementation, specifically the addition of the first parameter, the 'TWI_t *', that indicates which of the TWI interfaces you use. As an example, you would initialize 'TWIE' by calling the 'twi_init' function, passing the address of the TWIE interface:
twi_init(&(TWIE));
You can use multiple TWI interfaces at the same time this way, in either master or slave mode.
Call this function to initialize the TWI interface. By default, it will initialize in MASTER mode. To initialize the interface in SLAVE mode, call twi_setAddress() first.
void twi_init(TWI_t *pTWI); pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)')
Call this function to shut down the TWI interface.
void twi_shutdown(TWI_t *pTWI); pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)')
Call this function prior to twi_init() to set the slave address and switch to slave mode. If you do not call this function, twi_init() will initialize the interface in master mode.
void twi_setAddress(TWI_t *pTWI, uint8_t addr); pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)') addr - a 7-bit 2-wire address [additional bits not supported]
Call this function in MASTER mode to read data from a specified device. Note that the function will block until the data has been completely read, or the device indicates that it wants to terminate the connection. The 'wTimeout' flag allows you to specify a maximum time before the function returns anyway [useful if a device is not connected or is not responding for some reason, to avoid hanging the firmware]. A timeout of '0' waits indefinitely.
uint8_t twi_readFrom(TWI_t *pTWI, uint8_t addr, uint8_t *pBuf,
uint8_t cbBuf, uint8_t fStop, uint16_t wTimeout);
pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)')
addr - the 7-bit 2-wire address to read data from
pBuf - a pointer to a sufficiently sized buffer
cbBuf - the maximum size of the buffer (in bytes)
fStop - flag to indicate 'send stop' at end (non-zero sends stop)
wTimeout - maximum number of milliseconds to wait for the operation
to complete. A value of '0' waits indefinitely.
Call this function in MASTER mode to send data to a specified device. The function normally returns immediately, and the data is then sent asynchronously. You can specify a non-zero value for 'fWait' to wait until the data is actually sent before returning.
uint8_t twi_writeTo(TWI_t *pTWI, uint8_t addr, const uint8_t *pBuf,
uint8_t cbBuf, uint8_t fWait, uint8_t fStop);
pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)')
addr - the 7-bit 2-wire address to send data to
pBuf - a pointer to a buffer containing the data
cbBuf - the number of bytes to send
fWait - flag to indicate 'wait for completion' (non-zero waits)
fStop - flag to indicate 'send stop' at end (non-zero sends stop)
Call this in SLAVE mode from the function registered by twi_attachSlaveTxEvent(). The callback function will use 'twi_transmit()' to load data into an internal buffer, which will be sent asynchronously.
uint8_t twi_transmit(TWI_t *pTWI, const uint8_t *pBuf, uint8_t cbBuf); pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)') pBuf - a pointer to a buffer containing the data cbBuf - the number of bytes to send
For SLAVE mode, this function attaches a receive callback function (and context pointer for that callback function) for the specified 2-wire device. This function will be called once, at the end of the transaction, whenever the master sends data to this device. The parameters will point to the internal buffers that have been reserved for the specified TWI device, so it is possible to have multiple slaves (and masters) running at the same time if your CPU supports multiple TWI interfaces. The callback function is called in the context of an ISR, so you should not consume a lot of time, nor wait on anything, while in the context of callback.
void twi_attachSlaveRxEvent(TWI_t *pTWI,
void (*cbRX)(TWI_t *pTWIcb, void *pCtxtcb,
const uint8_t *pBuf, int cbBuf),
void *pCtxt );
pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)')
cbTX - callback for TX event
pTWIcb - pointer to TWI_t passed to the callback
pTWIcb - context pointer passed to the callback
pBuf - pointer to the buffer containing the received data
cbBuf - length of read buffer (number of bytes read)
pCtxt - pointer to 'context' (implementation-defined)
For SLAVE mode, this function attaches a transmit callback function (and context pointer for that callback function) for the specified 2-wire device. The ISR will call the assigned callback function whenever the master requests that data be sent, once per transaction. This call is done in the context of the ISR, so it should not consume a lot of time, nor wait on anything. The callback function will need to call twi_transmit() to send the data.
void twi_attachSlaveTxEvent(TWI_t *pTWI,
void (*cbTX)(TWI_t *pTWIcb, void *pCtxtcb),
void *pCtxt );
pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)')
cbTX - callback for TX event
pTWIcb - pointer to TWI_t passed to the callback
pTWIcb - context pointer passed to the callback
pCtxt - pointer to 'context' (implementation-defined)
This function is internal to the TWI interface, but may be invoked manually in MASTER mode, for those cases where a STOP has not already been sent [following reading or writing data].
void twi_stop(TWI_t *pTWI); pTWI - pointer to TWI_t for the TWI register (example: '&(TWIC)')