example using the two-wire interfacev(3)
NAME
Example using the two-wire interface (TWI) - 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.
For the original Philips documentation, see
http://www.semiconductors.philips.com/buses/i2c/index.html
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 opendrain 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].RS 4
- 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 [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.
Author
- Generated automatically by Doxygen for avr-libc from the source code.