LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2011.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2011  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  *  <b>Low Level API Example:</b>
  53  *  \code
  54  *      // Initialise the TWI driver before first use
  55  *      TWI_Init();
  56  *
  57  *      // Start a write session to device at device address 0xA0, internal address 0xDC with a 10ms timeout
  58  *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10))
  59  *      {
  60  *          TWI_SendByte(0xDC);
  61  *
  62  *          TWI_SendByte(0x01);
  63  *          TWI_SendByte(0x02);
  64  *          TWI_SendByte(0x03);
  65  *
  66  *          // Must stop transmission afterwards to release the bus
  67  *          TWI_StopTransmission();
  68  *      }
  69  *
  70  *      // Start a read session to device at address 0xA0, internal address 0xDC with a 10ms timeout
  71  *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10))
  72  *      {
  73  *          TWI_SendByte(0xDC);
  74  *          TWI_StopTransmission();
  75  *
  76  *          if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10))
  77  *          {
  78  *              uint8_t Byte1, Byte2, Byte3;
  79  *
  80  *              // Read three bytes, acknowledge after the third byte is received
  81  *              TWI_ReceiveByte(&Byte1, false);
  82  *              TWI_ReceiveByte(&Byte2, false);
  83  *              TWI_ReceiveByte(&Byte3, true);
  84  *
  85  *              // Must stop transmission afterwards to release the bus
  86  *              TWI_StopTransmission();
  87  *          }
  88  *      }
  89  *  \endcode
  90  *
  91  *  <b>High Level API Example:</b>
  92  *  \code
  93  *      // Initialise the TWI driver before first use
  94  *      TWI_Init();
  95  *
  96  *      // Start a write session to device at device address 0xA0, internal address 0xDC with a 10ms timeout
  97  *      uint8_t InternalWriteAddress = 0xDC;
  98  *      uint8_t WritePacket[3] = {0x01, 0x02, 0x03};
  99  *
 100  *      TWI_WritePacket(0xA0, 10, &InternalWriteAddress, sizeof(InternalWriteAddress),
 101  *                      &WritePacket, sizeof(WritePacket);
 102  *
 103  *      // Start a read session to device at address 0xA0, internal address 0xDC with a 10ms timeout
 104  *      uint8_t InternalReadAddress = 0xDC;
 105  *      uint8_t ReadPacket[3];
 106  *
 107  *      TWI_ReadPacket(0xA0, 10, &InternalReadAddress, sizeof(InternalReadAddress),
 108  *                     &ReadPacket, sizeof(ReadPacket);
 109  *  \endcode
 110  *
 111  *  @{
 112  */
 113
 114 #ifndef __TWI_AVRU4U6U7_H__
 115 #define __TWI_AVRU4U6U7_H__
 116
 117         /* Includes: */
 118                 #include "../../../Common/Common.h"
 119
 120                 #include <avr/io.h>
 121                 #include <stdbool.h>
 122                 #include <stdio.h>
 123                 #include <util/twi.h>
 124                 #include <util/delay.h>
 125
 126         /* Enable C linkage for C++ Compilers: */
 127                 #if defined(__cplusplus)
 128                         extern "C" {
 129                 #endif
 130
 131         /* Preprocessor Checks: */
 132                 #if !defined(__INCLUDE_FROM_TWI_H)
 133                         #error Do not include this file directly. Include LUFA/Drivers/Peripheral/TWI.h instead.
 134                 #endif
 135
 136         /* Public Interface - May be used in end-application: */
 137                 /* Macros: */
 138                         /** TWI slave device address mask for a read session. Mask with a slave device base address to obtain
 139                          *  the correct TWI bus address for the slave device when reading data from it.
 140                          */
 141                         #define TWI_ADDRESS_READ         0x00
 142
 143                         /** TWI slave device address mask for a write session. Mask with a slave device base address to obtain
 144                          *  the correct TWI bus address for the slave device when writing data to it.
 145                          */
 146                         #define TWI_ADDRESS_WRITE        0x01
 147
 148                         /** Mask to retrieve the base address for a TWI device, which can then be ORed with \ref TWI_ADDRESS_READ
 149                          *  or \ref TWI_ADDRESS_WRITE to obtain the device's read and write address respectively.
 150                          */
 151                         #define TWI_DEVICE_ADDRESS_MASK  0xFE
 152
 153                 /* Enums: */
 154                         /** Enum for the possible return codes of the TWI transfer start routine and other dependant TWI functions. */
 155                         enum TWI_ErrorCodes_t
 156                         {
 157                                 TWI_ERROR_NoError              = 0, /**< Indicates that the command completed sucessfully. */
 158                                 TWI_ERROR_BusFault             = 1, /**< A TWI bus fault occurred while attempting to capture the bus. */
 159                                 TWI_ERROR_BusCaptureTimeout    = 2, /**< A timeout occurred whilst waiting for the bus to be ready. */
 160                                 TWI_ERROR_SlaveResponseTimeout = 3, /**< No ACK received at the nominated slave address within the timeout period. */
 161                                 TWI_ERROR_SlaveNotReady        = 4, /**< Slave NAKed the TWI bus START condition. */
 162                                 TWI_ERROR_SlaveNAK             = 5, /**< Slave NAKed whilst attempting to send data to the device. */
 163                         };
 164
 165                 /* Inline Functions: */
 166                         /** Initialises the TWI hardware into master mode, ready for data transmission and reception. This must be
 167                          *  before any other TWI operations.
 168                          */
 169                         static inline void TWI_Init(void) ATTR_ALWAYS_INLINE;
 170                         static inline void TWI_Init(void)
 171                         {
 172                                 TWCR |=  (1 << TWEN);
 173                         }
 174
 175                         /** Turns off the TWI driver hardware. If this is called, any further TWI operations will require a call to
 176                          *  \ref TWI_Init() before the TWI can be used again.
 177                          */
 178                         static inline void TWI_ShutDown(void) ATTR_ALWAYS_INLINE;
 179                         static inline void TWI_ShutDown(void)
 180                         {
 181                                 TWCR &= ~(1 << TWEN);
 182                         }
 183
 184                         /** Sends a TWI STOP onto the TWI bus, terminating communication with the currently addressed device. */
 185                         static inline void TWI_StopTransmission(void) ATTR_ALWAYS_INLINE;
 186                         static inline void TWI_StopTransmission(void)
 187                         {
 188                                 TWCR = ((1 << TWINT) | (1 << TWSTO) | (1 << TWEN));
 189                         }
 190
 191                         /** Sends a byte to the currently addressed device on the TWI bus.
 192                          *
 193                          *  \param[in] Byte  Byte to send to the currently addressed device
 194                          *
 195                          *  \return Boolean \c true if the recipient ACKed the byte, \c false otherwise
 196                          */
 197                         static inline bool TWI_SendByte(const uint8_t Byte)
 198                         {
 199                                 TWDR = Byte;
 200                                 TWCR = ((1 << TWINT) | (1 << TWEN));
 201                                 while (!(TWCR & (1 << TWINT)));
 202
 203                                 return ((TWSR & TW_STATUS_MASK) == TW_MT_DATA_ACK);
 204                         }
 205
 206                         /** Receives a byte from the currently addressed device on the TWI bus.
 207                          *
 208                          *  \param[in] Byte      Location where the read byte is to be stored
 209                          *  \param[in] LastByte  Indicates if the byte should be ACKed if false, NAKed if true
 210                          *
 211                          *  \return Boolean \c true if the byte reception successfully completed, \c false otherwise
 212                          */
 213                         static inline uint8_t TWI_ReceiveByte(uint8_t* const Byte,
 214                                                               const bool LastByte)
 215                         {
 216                                 uint8_t TWCRMask = ((1 << TWINT) | (1 << TWEN));
 217
 218                                 if (!(LastByte))
 219                                   TWCRMask |= (1 << TWEA);
 220
 221                                 TWCR = TWCRMask;
 222                                 while (!(TWCR & (1 << TWINT)));
 223                                 *Byte = TWDR;
 224
 225                                 return ((TWSR & TW_STATUS_MASK) == TW_MR_DATA_ACK);
 226                         }
 227
 228                 /* Function Prototypes: */
 229                         /** Begins a master mode TWI bus communication with the given slave device address.
 230                          *
 231                          *  \param[in] SlaveAddress  Address of the slave TWI device to communicate with
 232                          *  \param[in] TimeoutMS     Timeout period within which the slave must respond, in milliseconds
 233                          *
 234                          *  \return A value from the \ref TWI_ErrorCodes_t enum
 235                          */
 236                         uint8_t TWI_StartTransmission(const uint8_t SlaveAddress,
 237                                                       const uint8_t TimeoutMS);
 238
 239                         /** High level function to perform a complete packet transfer over the TWI bus to the specified
 240                          *  device.
 241                          *
 242                          *  \param[in] SlaveAddress        Base address of the TWI slave device to communicate with
 243                          *  \param[in] TimeoutMS           Timeout for bus capture and slave START ACK, in milliseconds
 244                          *  \param[in] InternalAddress     Pointer to a location where the internal slave read start address is stored
 245                          *  \param[in] InternalAddressLen  Size of the internal device address, in bytes
 246                          *  \param[in] Buffer              Pointer to a buffer where the read packet data is to be stored
 247                          *  \param[in] Length              Size of the packet to read, in bytes
 248                          */
 249                         uint8_t TWI_ReadPacket(const uint8_t SlaveAddress,
 250                                                const uint8_t TimeoutMS,
 251                                                const uint8_t* InternalAddress,
 252                                                uint8_t InternalAddressLen,
 253                                                uint8_t* Buffer,
 254                                                uint8_t Length);
 255
 256                         /** High level function to perform a complete packet transfer over the TWI bus from the specified
 257                          *  device.
 258                          *
 259                          *  \param[in] SlaveAddress        Base address of the TWI slave device to communicate with
 260                          *  \param[in] TimeoutMS           Timeout for bus capture and slave START ACK, in milliseconds
 261                          *  \param[in] InternalAddress     Pointer to a location where the internal slave write start address is stored
 262                          *  \param[in] InternalAddressLen  Size of the internal device address, in bytes
 263                          *  \param[in] Buffer              Pointer to a buffer where the packet data to send is stored
 264                          *  \param[in] Length              Size of the packet to send, in bytes
 265                          */
 266                         uint8_t TWI_WritePacket(const uint8_t SlaveAddress,
 267                                                 const uint8_t TimeoutMS,
 268                                                 const uint8_t* InternalAddress,
 269                                                 uint8_t InternalAddressLen,
 270                                                 const uint8_t* Buffer,
 271                                                 uint8_t Length);
 272
 273         /* Disable C linkage for C++ Compilers: */
 274                 #if defined(__cplusplus)
 275                         }
 276                 #endif
 277
 278 #endif
 279
 280 /** @} */
 281