Some newer devices of the ATmega series contain builtin support for interfacing the
microcontroller to a two-wire bus, called TWI. This is essentially the same called I2C by
Philips, but that term is avoided in Atmel's documentation due to patenting issues.
Introduction into TWI
The two-wire interface consists of two signal lines named SDA
(serial data) and SCL (serial clock) (plus a ground line, of course).
All devices participating in the bus are connected together, using open-drain driver
circuitry, so the wires must be terminated using appropriate pullup resistors. The pullups
must be small enough to recharge the line capacity in short enough time compared to the
desired maximal clock frequency, yet large enough so all drivers will not be overloaded.
There are formulas in the datasheet that help selecting the pullups.
Devices can either act as a master to the bus (i. e., they initiate a transfer), or as
a slave (they only act when being called by a master). The bus is multi-master capable,
and a particular device implementation can act as either master or slave at different
times. Devices are addressed using a 7-bit address (coordinated by Philips) transfered as
the first byte after the so-called start condition. The LSB of that byte is R/~W, i. e. it
determines whether the request to the slave is to read or write data during the next
cycles. (There is also an option to have devices using 10-bit addresses but that is not
covered by this example.)
The TWI example project
The ATmega TWI hardware supports both, master and slave operation. This example will
only demonstrate how to use an AVR microcontroller as TWI master. The implementation is
kept simple in order to concentrate on the steps that are required to talk to a TWI slave,
so all processing is done in polled-mode, waiting for the TWI interface to indicate that
the next processing step is due (by setting the TWINT interrupt bit). If it is desired to
have the entire TWI communication happen in "background", all this can be implemented in
an interrupt-controlled way, where only the start condition needs to be triggered from
outside the interrupt routine.
There is a variety of slave devices available that can be connected to a TWI bus. For
the purpose of this example, an EEPROM device out of the industry-standard
24Cxx series has been chosen (where
xx can be one of 01, 02, 04,
08, or 16) which are available from various vendors. The
choice was almost arbitrary, mainly triggered by the fact that an EEPROM device is being
talked to in both directions, reading and writing the slave device, so the example will
demonstrate the details of both.
Usually, there is probably not much need to add more EEPROM to an ATmega system that
way: the smallest possible AVR device that offers hardware TWI support is the ATmega8
which comes with 512 bytes of EEPROM, which is equivalent to an 24C04 device. The
ATmega128 already comes with twice as much EEPROM as the 24C16 would offer. One exception
might be to use an externally connected EEPROM device that is removable; e. g. SDRAM PC
memory comes with an integrated TWI EEPROM that carries the RAM configuration
information.
The Source Code
- Note [1]
The header file
<util/twi.h>
contains some macro definitions for symbolic
constants used in the TWI status register. These definitions match the names used in the
Atmel datasheet except that all names have been prefixed with
TW_
.
- Note [2]
The clock is used
in timer calculations done by the compiler, for the UART baud rate and the TWI clock
rate.
- Note [3]
The address
assigned for the 24Cxx EEPROM consists of 1010 in the upper four bits. The following three
bits are normally available as slave sub-addresses, allowing to operate more than one
device of the same type on a single bus, where the actual subaddress used for each device
is configured by hardware strapping. However, since the next data packet following the
device selection only allows for 8 bits that are used as an EEPROM address, devices that
require more than 8 address bits (24C04 and above) "steal" subaddress bits and use them
for the EEPROM cell address bits 9 to 11 as required. This example simply assumes all
subaddress bits are 0 for the smaller devices, so the E0, E1, and E2 inputs of the 24Cxx
must be grounded.
- Note [3a]
EEPROMs of type
24C32 and above cannot be addressed anymore even with the subaddress bit trick. Thus, they
require the upper address bits being sent separately on the bus. When activating the
WORD_ADDRESS_16BIT
define, the algorithm implements
that auxiliary address byte transmission.
- Note [4]
For slow clocks,
enable the 2 x U[S]ART clock multiplier, to improve the baud rate error. This will allow a
9600 Bd communication using the standard 1 MHz calibrated RC oscillator. See also the Baud
rate tables in the datasheets.
- Note [5]
The datasheet
explains why a minimum TWBR value of 10 should be maintained when running in master mode.
Thus, for system clocks below 3.6 MHz, we cannot run the bus at the intented clock rate of
100 kHz but have to slow down accordingly.
- Note [6]
This function is
used by the standard output facilities that are utilized in this example for debugging and
demonstration purposes.
- Note [7]
In order to shorten
the data to be sent over the TWI bus, the 24Cxx EEPROMs support multiple data bytes
transfered within a single request, maintaining an internal address counter that is
updated after each data byte transfered successfully. When reading data, one request can
read the entire device memory if desired (the counter would wrap around and start back
from 0 when reaching the end of the device).
- Note [8]
When reading the
EEPROM, a first device selection must be made with write intent (R/~W bit set to 0
indicating a write operation) in order to transfer the EEPROM address to start reading
from. This is called
master transmitter mode. Each completion of a
particular step in TWI communication is indicated by an asserted TWINT bit in TWCR. (An
interrupt would be generated if allowed.) After performing any actions that are needed for
the next communication step, the interrupt condition must be manually cleared by
setting the TWINT bit. Unlike with many other interrupt sources,
this would even be required when using a true interrupt routine, since as soon as TWINT is
re-asserted, the next bus transaction will start.
- Note [9]
Since the TWI bus
is multi-master capable, there is potential for a bus contention when one master starts to
access the bus. Normally, the TWI bus interface unit will detect this situation, and will
not initiate a start condition while the bus is busy. However, in case two masters were
starting at exactly the same time, the way bus arbitration works, there is always a chance
that one master could lose arbitration of the bus during any transmit operation. A master
that has lost arbitration is required by the protocol to immediately cease talking on the
bus; in particular it must not initiate a stop condition in order to not corrupt the
ongoing transfer from the active master. In this example, upon detecting a lost
arbitration condition, the entire transfer is going to be restarted. This will cause a new
start condition to be initiated, which will normally be delayed until the currently active
master has released the bus.
- Note [10]
Next, the device
slave is going to be reselected (using a so-called repeated start condition which is meant
to guarantee that the bus arbitration will remain at the current master) using the same
slave address (SLA), but this time with read intent (R/~W bit set to 1) in order to
request the device slave to start transfering data from the slave to the master in the
next packet.
- Note [11]
If the EEPROM
device is still busy writing one or more cells after a previous write request, it will
simply leave its bus interface drivers at high impedance, and does not respond to a
selection in any way at all. The master selecting the device will see the high level at
SDA after transfering the SLA+R/W packet as a NACK to its selection request. Thus, the
select process is simply started over (effectively causing a
repeated start
condition), until the device will eventually respond. This polling procedure
is recommended in the 24Cxx datasheet in order to minimize the busy wait time when
writing. Note that in case a device is broken and never responds to a selection (e. g.
since it is no longer present at all), this will cause an infinite loop. Thus the maximal
number of iterations made until the device is declared to be not responding at all, and an
error is returned, will be limited to MAX_ITER.
- Note [12]
This is called
master receiver mode: the bus master still supplies the SCL clock,
but the device slave drives the SDA line with the appropriate data. After 8 data bits, the
master responds with an ACK bit (SDA driven low) in order to request another data transfer
from the slave, or it can leave the SDA line high (NACK), indicating to the slave that it
is going to stop the transfer now. Assertion of ACK is handled by setting the TWEA bit in
TWCR when starting the current transfer.
- Note [13]
The control word
sent out in order to initiate the transfer of the next data packet is initially set up to
assert the TWEA bit. During the last loop iteration, TWEA is de-asserted so the client
will get informed that no further transfer is desired.
- Note [14]
Except in the case
of lost arbitration, all bus transactions must properly be terminated by the master
initiating a stop condition.
- Note [15]
Writing to the
EEPROM device is simpler than reading, since only a master transmitter mode transfer is
needed. Note that the first packet after the SLA+W selection is always considered to be
the EEPROM address for the next operation. (This packet is exactly the same as the one
above sent before starting to read the device.) In case a master transmitter mode transfer
is going to send more than one data packet, all following packets will be considered data
bytes to write at the indicated address. The internal address pointer will be incremented
after each write operation.
- Note [16]
24Cxx devices can
become write-protected by strapping their ~WC pin to logic high. (Leaving it unconnected
is explicitly allowed, and constitutes logic low level, i. e. no write protection.) In
case of a write protected device, all data transfer attempts will be NACKed by the device.
Note that some devices might not implement this.