LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2010.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *  \brief TWI peripheral driver for the U7, U6 and U4 USB AVRs.
  33  *
  34  *  Master mode TWI driver for the AT90USB1287, AT90USB1286, AT90USB647, AT90USB646, ATMEGA16U4 and ATMEGA32U4 AVRs.
  35  *
  36  *  \note This file should not be included directly. It is automatically included as needed by the TWI driver
  37  *        dispatch header located in LUFA/Drivers/Peripheral/TWI.h.
  38  */
  39
  40 /** \ingroup Group_TWI
  41  *  @defgroup Group_TWI_AVRU4U6U7 Series U4, U6 and U7 Model TWI Driver
  42  *
  43  *  Master mode TWI driver for the AT90USB1287, AT90USB1286, AT90USB647, AT90USB646, ATMEGA16U4 and ATMEGA32U4 AVRs.
  44  *
  45  *  \note This file should not be included directly. It is automatically included as needed by the TWI driver
  46  *        dispatch header located in LUFA/Drivers/Peripheral/TWI.h.
  47  *
  48  *  <b>Example Usage:</b>
  49  *  \code
  50  *      // Initialise the TWI driver before first use
  51  *      TWI_Init();
  52  *
  53  *      // Start a write session to device at address 0xA0 with a 10ms timeout
  54  *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10))
  55  *      {
  56  *          TWI_SendByte(0x01);
  57  *          TWI_SendByte(0x02);
  58  *          TWI_SendByte(0x03);
  59  *
  60  *          // Must stop transmission afterwards to release the bus
  61  *          TWI_StopTransmission();
  62  *      }
  63  *
  64  *      // Start a read session to device at address 0xA0 with a 10ms timeout
  65  *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10))
  66  *      {
  67  *          uint8_t Byte1, Byte2, Byte3;
  68  *
  69  *          // Read three bytes, acknowledge after the third byte is received
  70  *          TWI_ReceiveByte(&Byte1, false);
  71  *          TWI_ReceiveByte(&Byte2, false);
  72  *          TWI_ReceiveByte(&Byte3, true);
  73  *
  74  *          // Must stop transmission afterwards to release the bus
  75  *          TWI_StopTransmission();
  76  *      }
  77  *  \endcode
  78  *
  79  *  @{
  80  */
  81
  82 #ifndef __TWI_AVRU4U6U7_H__
  83 #define __TWI_AVRU4U6U7_H__
  84
  85         /* Includes: */
  86                 #include "../../../Common/Common.h"
  87
  88                 #include <avr/io.h>
  89                 #include <stdbool.h>
  90                 #include <util/twi.h>
  91                 #include <util/delay.h>
  92
  93         /* Enable C linkage for C++ Compilers: */
  94                 #if defined(__cplusplus)
  95                         extern "C" {
  96                 #endif
  97
  98         /* Preprocessor Checks: */
  99                 #if !defined(__INCLUDE_FROM_TWI_H)
 100                         #error Do not include this file directly. Include LUFA/Drivers/Peripheral/TWI.h instead.
 101                 #endif
 102
 103         /* Public Interface - May be used in end-application: */
 104                 /* Macros: */
 105                         /** TWI slave device address mask for a read session. Mask with a slave device base address to obtain
 106                          *  the correct TWI bus address for the slave device when reading data from it.
 107                          */
 108                         #define TWI_ADDRESS_READ        0x00
 109
 110                         /** TWI slave device address mask for a write session. Mask with a slave device base address to obtain
 111                          *  the correct TWI bus address for the slave device when writing data to it.
 112                          */
 113                         #define TWI_ADDRESS_WRITE       0x01
 114
 115                 /* Inline Functions: */
 116                         /** Initialises the TWI hardware into master mode, ready for data transmission and reception. This must be
 117                          *  before any other TWI operations.
 118                          */
 119                         static inline void TWI_Init(void) ATTR_ALWAYS_INLINE;
 120                         static inline void TWI_Init(void)
 121                         {
 122                                 TWCR |=  (1 << TWEN);
 123                         }
 124
 125                         /** Turns off the TWI driver hardware. If this is called, any further TWI operations will require a call to
 126                          *  \ref TWI_Init() before the TWI can be used again.
 127                          */
 128                         static inline void TWI_ShutDown(void) ATTR_ALWAYS_INLINE;
 129                         static inline void TWI_ShutDown(void)
 130                         {
 131                                 TWCR &= ~(1 << TWEN);
 132                         }
 133
 134                         /** Sends a TWI STOP onto the TWI bus, terminating communication with the currently addressed device. */
 135                         static inline void TWI_StopTransmission(void) ATTR_ALWAYS_INLINE;
 136                         static inline void TWI_StopTransmission(void)
 137                         {
 138                                 TWCR = ((1 << TWINT) | (1 << TWSTO) | (1 << TWEN));
 139                         }
 140
 141                         /** Sends a byte to the currently addressed device on the TWI bus.
 142                          *
 143                          *  \param[in] Byte  Byte to send to the currently addressed device
 144                          *
 145                          *  \return Boolean true if the recipient ACKed the byte, false otherwise
 146                          */
 147                         static inline bool TWI_SendByte(const uint8_t Byte)
 148                         {
 149                                 TWDR = Byte;
 150                                 TWCR = ((1 << TWINT) | (1 << TWEN));
 151                                 while (!(TWCR & (1 << TWINT)));
 152
 153                                 return ((TWSR & TW_STATUS_MASK) == TW_MT_DATA_ACK);
 154                         }
 155
 156                         /** Receives a byte from the currently addressed device on the TWI bus.
 157                          *
 158                          *  \param[in] Byte      Location where the read byte is to be stored
 159                          *  \param[in] LastByte  Indicates if the byte should be ACKed if false, NAKed if true
 160                          *
 161                          *  \return Boolean true if the byte reception successfully completed, false otherwise
 162                          */
 163                         static inline bool TWI_ReceiveByte(uint8_t* const Byte,
 164                                                            const bool LastByte)
 165                         {
 166                                 uint8_t TWCRMask = ((1 << TWINT) | (1 << TWEN));
 167
 168                                 if (!(LastByte))
 169                                   TWCRMask |= (1 << TWEA);
 170
 171                                 TWCR = TWCRMask;
 172                                 while (!(TWCR & (1 << TWINT)));
 173                                 *Byte = TWDR;
 174
 175                                 return ((TWSR & TW_STATUS_MASK) == TW_MR_DATA_ACK);
 176                         }
 177
 178                 /* Function Prototypes: */
 179                         /** Begins a master mode TWI bus communication with the given slave device address.
 180                          *
 181                          *  \param[in] SlaveAddress  Address of the slave TWI device to communicate with
 182                          *  \param[in] TimeoutMS     Timeout period within which the slave must respond, in milliseconds
 183                          *
 184                          *  \return Boolean true if the device is ready for data, false otherwise
 185                          */
 186                         bool TWI_StartTransmission(const uint8_t SlaveAddress,
 187                                                    const uint8_t TimeoutMS);
 188
 189         /* Disable C linkage for C++ Compilers: */
 190                 #if defined(__cplusplus)
 191                         }
 192                 #endif
 193
 194 #endif
 195
 196 /** @} */
 197