/* Copyright (c) 2002, Joerg Wunsch
   All rights reserved.

   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions are met:

   * Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in
     the documentation and/or other materials provided with the
     distribution.

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  POSSIBILITY OF SUCH DAMAGE. */

/* $Id: twitest.dox,v 1.8 2005/12/29 20:16:55 joerg_wunsch Exp $ */

/** \defgroup twi_demo Example using the two-wire interface (TWI)
    \ingroup demos

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

\section twi_demo_intro Introduction into TWI

The two-wire interface consists of two signal lines named \e SDA
(serial data) and \e 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.)

\section twi_demo_project 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 <strong>24C<em>xx</em></strong> series has been
chosen (where \e xx can be one of \b 01, \b 02, \b 04, \b 08, or
<b>16</b>) 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.

\section twi_demo_src The Source Code

\htmlonly
Source file: <a href="../examples/twitest/twitest.c">twitest.c</a>
\endhtmlonly

\latexonly
The source code is installed under

\texttt{\$prefix/share/doc/avr-libc/examples/twitest/twitest.c},

where \texttt{\$prefix} is a configuration option.  For Unix
systems, it is usually set to either \texttt{/usr} or
\texttt{/usr/local}.
\endlatexonly

\par Note [1]

The header file <tt>&lt;util/twi.h&gt;</tt> 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 \c TW_.

\par Note [2]

The clock is used in timer calculations done by the compiler, for the
UART baud rate and the TWI clock rate.

\par 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.

\par 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.

\par 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.

\par Note [6]

This function is used by the standard output facilities that are
utilized in this example for debugging and demonstration purposes.

\par 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).

\par 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
<em>master transmitter mode</em>.  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 \e 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.

\par 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.

\par 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.

\par 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 <em>repeated start condition</em>), 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.

\par Note [12]

This is called <em>master receiver mode</em>: 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.

\par 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.

\par Note [14]

Except in the case of lost arbitration, all bus transactions must
properly be terminated by the master initiating a stop condition.

\par 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.

\par 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.

*/