27.6 Using the TWI

The AVR TWI is byte-oriented and interrupt based. Interrupts are issued after all bus events, like reception of a byte or transmission of a START condition. Because the TWI is interrupt-based, the application software is free to carry on other operations during a TWI byte transfer. Note that the TWI Interrupt Enable (TWIE) bit in TWCRn together with the Global Interrupt Enable bit in SREG allow the application to decide whether or not assertion of the TWINT Flag should generate an interrupt request. If the TWIE bit is cleared, the application must poll the TWINT Flag in order to detect actions on the TWI bus.

When the TWINT Flag is asserted, the TWI has finished an operation and awaits application response. In this case, the TWI Status Register (TWSRn) contains a value indicating the current state of the TWI bus. The application software can then decide how the TWI should behave in the next TWI bus cycle by manipulating the TWCRn and TWDRn Registers.

The following figure illustrates a simple example of how the application can interface to the TWI hardware. In this example, a Master wishes to transmit a single data byte to a Slave. A more detailed explanation follows later in this section. Simple code examples are presented in the table below.

1. The first step in a TWI transmission is to transmit a START condition. This is done by writing a specific value into TWCRn, instructing the TWI n hardware to transmit a START condition. Which value to write is described later on. However, it is important that the TWINT bit is set in the value written. Writing a one to TWINT clears the flag. The TWI n will not start any operation as long as the TWINT bit in TWCRn is set. Immediately after the application has cleared TWINT, the TWI n will initiate transmission of the START condition.
2. When the START condition has been transmitted, the TWINT Flag in TWCRn is set, and TWSRn is updated with a status code indicating that the START condition has successfully been sent.
3. The application software should now examine the value of TWSRn, to make sure that the START condition was successfully transmitted. If TWSRn indicates otherwise, the application software might take some special action, like calling an error routine. Assuming that the status code is as expected, the application must load SLA+W into TWDR. Remember that TWDRn is used both for address and data. After TWDRn has been loaded with the desired SLA+W, a specific value must be written to TWCRn, instructing the TWI n hardware to transmit the SLA+W present in TWDRn. Which value to write is described later on. However, it is important that the TWINT bit is set in the value written. Writing a one to TWINT clears the flag. The TWI will not start any operation as long as the TWINT bit in TWCRn is set. Immediately after the application has cleared TWINT, the TWI will initiate transmission of the address packet.
4. When the address packet has been transmitted, the TWINT Flag in TWCRn is set, and TWSRn is updated with a status code indicating that the address packet has successfully been sent. The status code will also reflect whether a Slave acknowledged the packet or not.
5. The application software should now examine the value of TWSRn, to make sure that the address packet was successfully transmitted, and that the value of the ACK bit was as expected. If TWSRn indicates otherwise, the application software might take some special action, like calling an error routine. Assuming that the status code is as expected, the application must load a data packet into TWDRn. Subsequently, a specific value must be written to TWCRn, instructing the TWI n hardware to transmit the data packet present in TWDRn. Which value to write is described later on. However, it is important that the TWINT bit is set in the value written. Writing a one to TWINT clears the flag. The TWI n will not start any operation as long as the TWINT bit in TWCRn is set. Immediately after the application has cleared TWINT, the TWI will initiate transmission of the data packet.
6. When the data packet has been transmitted, the TWINT Flag in TWCRn is set, and TWSRn is updated with a status code indicating that the data packet has successfully been sent. The status code will also reflect whether a Slave acknowledged the packet or not.
7. The application software should now examine the value of TWSRn, to make sure that the data packet was successfully transmitted, and that the value of the ACK bit was as expected. If TWSR indicates otherwise, the application software might take some special action, like calling an error routine. Assuming that the status code is as expected, the application must write a specific value to TWCRn, instructing the TWI n hardware to transmit a STOP condition. Which value to write is described later on. However, it is important that the TWINT bit is set in the value written. Writing a one to TWINT clears the flag. The TWI n will not start any operation as long as the TWINT bit in TWCRn is set. Immediately after the application has cleared TWINT, the TWI will initiate transmission of the STOP condition. Note that TWINT is not set after a STOP condition has been sent.

Even though this example is simple, it shows the principles involved in all TWI transmissions. These can be summarized as follows:

• When the TWI has finished an operation and expects application response, the TWINT Flag is set. The SCL line is pulled low until TWINT is cleared.
• When the TWINT Flag is set, the user must update all TWI n Registers with the value relevant for the next TWI n bus cycle. As an example, TWDRn must be loaded with the value to be transmitted in the next bus cycle.
• After all TWI n Register updates and other pending application software tasks have been completed, TWCRn is written. When writing TWCRn, the TWINT bit should be set. Writing a one to TWINT clears the flag. The TWI n will then commence executing whatever operation was specified by the TWCRn setting.

The following table lists assembly and C implementation examples for TWI0. Note that the code below assumes that several definitions have been made, e.g. by using include-files.

ldi r16, (1<<TWINT)|(1<<TWSTA)|(1<<TWEN) 
out TWCR0, r16

TWCR0 = (1<<TWINT)|(1<<TWSTA)|(1<<TWEN)

wait1: 
in r16,TWCR0 
sbrs r16,TWINT 
rjmp wait1

while (!(TWCR0 & (1<<TWINT)));

in r16,TWSR0 
andi r16, 0xF8 
cpi r16, START 
brne ERROR

if ((TWSR0 & 0xF8) != START)
  ERROR();

ldi r16, SLA_W 
out TWDR0, r16 
ldi r16, (1<<TWINT) | (1<<TWEN) 
out TWCR0, r16

TWDR0 = SLA_W; 
TWCR0 = (1<<TWINT) | (1<<TWEN);

wait2: 
in r16,TWCR0 
sbrs r16,TWINT 
rjmp wait2

while (!(TWCR0 & (1<<TWINT)));

in r16,TWSR0 
andi r16, 0xF8 
cpi r16, MT_SLA_ACK 
brne ERROR

if ((TWSR0 & 0xF8) != MT_SLA_ACK) ERROR();

ldi r16, DATA 
out TWDR0, r16 
ldi r16, (1<<TWINT) | (1<<TWEN) 
out TWCR, r16

TWDR0 = DATA; 
TWCR0 = (1<<TWINT) | (1<<TWEN);

wait3: 
in r16,TWCR0 
sbrs r16,TWINT 
rjmp wait3

while (!(TWCR0 & (1<<TWINT)));

in r16,TWSR0 
andi r16, 0xF8 
cpi r16, MT_DATA_ACK 
brne ERROR

if ((TWSR0 & 0xF8) != MT_DATA_ACK) ERROR();

ldi r16, (1<<TWINT)|(1<<TWEN)| (1<<TWSTO) 
out TWCR0, r16 

TWCR0 = (1<<TWINT)|(1<<TWEN)|(1<<TWSTO);