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  *  \section Sec_ExampleUsage Example Usage
  49  *  The following snippet is an example of how this module may be used within a typical
  50  *  application.
  51  *
  52  *  \code
  53  *      // Initialise the TWI driver before first use
  54  *      TWI_Init();
  55  *
  56  *      // Start a write session to device at address 0xA0 with a 10ms timeout
  57  *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10))
  58  *      {
  59  *          TWI_SendByte(0x01);
  60  *          TWI_SendByte(0x02);
  61  *          TWI_SendByte(0x03);
  62  *
  63  *          // Must stop transmission afterwards to release the bus
  64  *          TWI_StopTransmission();
  65  *      }
  66  *
  67  *      // Start a read session to device at address 0xA0 with a 10ms timeout
  68  *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10))
  69  *      {
  70  *          uint8_t Byte1, Byte2, Byte3;
  71  *
  72  *          // Read three bytes, acknowledge after the third byte is received
  73  *          TWI_ReceiveByte(&Byte1, false);
  74  *          TWI_ReceiveByte(&Byte2, false);
  75  *          TWI_ReceiveByte(&Byte3, true);
  76  *
  77  *          // Must stop transmission afterwards to release the bus
  78  *          TWI_StopTransmission();
  79  *      }
  80  *  \endcode
  81  *
  82  *  @{
  83  */
  84
  85 #ifndef __TWI_AVRU4U6U7_H__
  86 #define __TWI_AVRU4U6U7_H__
  87
  88         /* Includes: */
  89                 #include "../../../Common/Common.h"
  90
  91                 #include <avr/io.h>
  92                 #include <stdbool.h>
  93                 #include <util/twi.h>
  94                 #include <util/delay.h>
  95
  96         /* Enable C linkage for C++ Compilers: */
  97                 #if defined(__cplusplus)
  98                         extern "C" {
  99                 #endif
 100
 101         /* Preprocessor Checks: */
 102                 #if !defined(__INCLUDE_FROM_TWI_H)
 103                         #error Do not include this file directly. Include LUFA/Drivers/Peripheral/TWI.h instead.
 104                 #endif
 105
 106         /* Public Interface - May be used in end-application: */
 107                 /* Macros: */
 108                         /** TWI slave device address mask for a read session. Mask with a slave device base address to obtain
 109                          *  the correct TWI bus address for the slave device when reading data from it.
 110                          */
 111                         #define TWI_ADDRESS_READ        0x00
 112
 113                         /** TWI slave device address mask for a write session. Mask with a slave device base address to obtain
 114                          *  the correct TWI bus address for the slave device when writing data to it.
 115                          */
 116                         #define TWI_ADDRESS_WRITE       0x01
 117
 118                 /* Inline Functions: */
 119                         /** Initialises the TWI hardware into master mode, ready for data transmission and reception. This must be
 120                          *  before any other TWI operations.
 121                          */
 122                         static inline void TWI_Init(void) ATTR_ALWAYS_INLINE;
 123                         static inline void TWI_Init(void)
 124                         {
 125                                 TWCR |=  (1 << TWEN);
 126                         }
 127
 128                         /** Turns off the TWI driver hardware. If this is called, any further TWI operations will require a call to
 129                          *  \ref TWI_Init() before the TWI can be used again.
 130                          */
 131                         static inline void TWI_ShutDown(void) ATTR_ALWAYS_INLINE;
 132                         static inline void TWI_ShutDown(void)
 133                         {
 134                                 TWCR &= ~(1 << TWEN);
 135                         }
 136
 137                         /** Sends a TWI STOP onto the TWI bus, terminating communication with the currently addressed device. */
 138                         static inline void TWI_StopTransmission(void) ATTR_ALWAYS_INLINE;
 139                         static inline void TWI_StopTransmission(void)
 140                         {
 141                                 TWCR = ((1 << TWINT) | (1 << TWSTO) | (1 << TWEN));
 142                         }
 143
 144                         /** Sends a byte to the currently addressed device on the TWI bus.
 145                          *
 146                          *  \param[in] Byte  Byte to send to the currently addressed device
 147                          *
 148                          *  \return Boolean true if the recipient ACKed the byte, false otherwise
 149                          */
 150                         static inline bool TWI_SendByte(const uint8_t Byte)
 151                         {
 152                                 TWDR = Byte;
 153                                 TWCR = ((1 << TWINT) | (1 << TWEN));
 154                                 while (!(TWCR & (1 << TWINT)));
 155
 156                                 return ((TWSR & TW_STATUS_MASK) == TW_MT_DATA_ACK);
 157                         }
 158
 159                         /** Receives a byte from the currently addressed device on the TWI bus.
 160                          *
 161                          *  \param[in] Byte      Location where the read byte is to be stored
 162                          *  \param[in] LastByte  Indicates if the byte should be ACKed if false, NAKed if true
 163                          *
 164                          *  \return Boolean true if the byte reception successfully completed, false otherwise
 165                          */
 166                         static inline bool TWI_ReceiveByte(uint8_t* const Byte,
 167                                                            const bool LastByte)
 168                         {
 169                                 uint8_t TWCRMask = ((1 << TWINT) | (1 << TWEN));
 170
 171                                 if (!(LastByte))
 172                                   TWCRMask |= (1 << TWEA);
 173
 174                                 TWCR = TWCRMask;
 175                                 while (!(TWCR & (1 << TWINT)));
 176                                 *Byte = TWDR;
 177
 178                                 return ((TWSR & TW_STATUS_MASK) == TW_MR_DATA_ACK);
 179                         }
 180
 181                 /* Function Prototypes: */
 182                         /** Begins a master mode TWI bus communication with the given slave device address.
 183                          *
 184                          *  \param[in] SlaveAddress  Address of the slave TWI device to communicate with
 185                          *  \param[in] TimeoutMS     Timeout period within which the slave must respond, in milliseconds
 186                          *
 187                          *  \return Boolean true if the device is ready for data, false otherwise
 188                          */
 189                         bool TWI_StartTransmission(const uint8_t SlaveAddress,
 190                                                    const uint8_t TimeoutMS);
 191
 192         /* Disable C linkage for C++ Compilers: */
 193                 #if defined(__cplusplus)
 194                         }
 195                 #endif
 196
 197 #endif
 198
 199 /** @} */
 200