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 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 [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.
Version 1.6.8 TExample1using0the two-wire interface (TWI)(3)