1 /** 2 * \file 3 * 4 * \brief TWI Master Mode management 5 * 6 * Copyright (c) 2010-2015 Atmel Corporation. All rights reserved. 7 * 8 * \asf_license_start 9 * 10 * \page License 11 * 12 * Redistribution and use in source and binary forms, with or without 13 * modification, are permitted provided that the following conditions are met: 14 * 15 * 1. Redistributions of source code must retain the above copyright notice, 16 * this list of conditions and the following disclaimer. 17 * 18 * 2. Redistributions in binary form must reproduce the above copyright notice, 19 * this list of conditions and the following disclaimer in the documentation 20 * and/or other materials provided with the distribution. 21 * 22 * 3. The name of Atmel may not be used to endorse or promote products derived 23 * from this software without specific prior written permission. 24 * 25 * 4. This software may only be redistributed and used in connection with an 26 * Atmel microcontroller product. 27 * 28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 38 * POSSIBILITY OF SUCH DAMAGE. 39 * 40 * \asf_license_stop 41 * 42 */ 43 /* 44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a> 45 */ 46 #ifndef TWI_MASTER_H_INCLUDED 47 #define TWI_MASTER_H_INCLUDED 48 49 #include <compiler.h> 50 51 #if (SAM4L) 52 # include "sam_twim/twi_master.h" 53 #elif (SAM3S || SAM3U || SAM3N || SAM3XA || SAM4S || SAM4E || SAM4N || SAM4C || SAMG || SAM4CP || SAM4CM) 54 # include "sam_twi/twi_master.h" 55 #elif XMEGA 56 # include "xmega_twi/twi_master.h" 57 #elif MEGA_RF 58 # include "megarf_twi/twi_master.h" 59 #elif UC3 60 # if (defined AVR32_TWI) 61 # include "uc3_twi/twi_master.h" 62 # else 63 # include "uc3_twim/twi_master.h" 64 # endif 65 #else 66 # error Unsupported chip type 67 #endif 68 69 /** 70 * 71 * \defgroup twi_group Two Wire-interface(TWI) 72 * 73 * This is the common API for TWIs. Additional features are available 74 * in the documentation of the specific modules. 75 * 76 * See \ref twi_quickstart. 77 * 78 * \section twi_group_platform Platform Dependencies 79 * 80 * The TWI API is partially chip- or platform-specific. While all 81 * platforms provide mostly the same functionality, there are some 82 * variations around how different bus types and clock tree structures 83 * are handled. 84 * 85 * The following functions are available on all platforms, but there may 86 * be variations in the function signature (i.e. parameters) and 87 * behaviour. These functions are typically called by platform-specific 88 * parts of drivers, and applications that aren't intended to be 89 * portable: 90 * - Master TWI Module initialization 91 * \code status_code_t twi_master_setup(*twi_module_pointer, twi_master_options_t *opt) \endcode 92 * - Enables TWI Module 93 * \code void twi_master_enable(*twi_module_pointer) \endcode 94 * - Disables TWI Module 95 * \code void twi_master_disable(*twi_module_pointer) \endcode 96 * - Read data from a slave device 97 * \code status_code_t twi_master_read(*twi_module_pointer, twi_package_t *package) \endcode 98 * - Write data from to a slave device 99 * \code status_code_t twi_master_write(*twi_module_pointer, twi_package_t *package) \endcode 100 * 101 * @{ 102 */ 103 104 /** 105 * \typedef twi_master_t 106 * This type can be used independently to refer to TWI master module for the 107 * architecture used. It refers to the correct type definition for the 108 * architecture, ie. TWI_t* for XMEGA or avr32_twim_t* for UC3 109 */ 110 111 //! @} 112 113 114 /** 115 * \page twi_quickstart Quickstart guide for Common service TWI 116 * 117 * This is the quickstart guide for the \ref twi_group "Common service TWI", 118 * with step-by-step instructions on how to configure and use the driver in a 119 * selection of use cases. 120 * 121 * The use cases contain several code fragments. The code fragments in the 122 * steps for setup can be copied into a custom initialization function, while 123 * the steps for usage can be copied into, e.g., the main application function. 124 * 125 * \section twi_basic_use_case Basic use case 126 * In the most basic use case, the TWI module is configured for 127 * - Master operation 128 * - addressing one slave device of the bus at address 0x50 129 * - TWI clock of 50kHz 130 * - polled read/write handling 131 * 132 * \section twi_basic_use_case_setup Setup steps 133 * \subsection twi_basic_use_case_setup_code Example code 134 * Add to your application C-file: 135 * \code 136 void twi_init(void) 137 { 138 twi_master_options_t opt = { 139 .speed = 50000, 140 .chip = 0x50 141 }; 142 143 twi_master_setup(&TWIM0, &opt); 144 } 145 \endcode 146 * 147 * \subsection twi_basic_use_case_setup_flow Workflow 148 * -# Ensure that board_init() has configured selected I/Os for TWI function. 149 * -# Ensure that \ref conf_twim.h is present for the driver. 150 * - \note This file is only for the driver and should not be included by the 151 * user. 152 * -# Define and initialize config structs for TWI module in your TWI initialization 153 * function: 154 * - \code 155 twi_master_options_t opt = { 156 .speed = 50000, 157 .chip = 0x50 158 }; \endcode 159 * - field \ref speed sets the baudrate of the TWI bus 160 * - field \ref chip sets the address of the slave device you want to communicate with 161 * -# Call twi_master_setup and optionally check its return code 162 * - \note The config structs can be reused for other TWI modules 163 * after this step. Simply reconfigure and write to others modules. 164 * 165 * \section twi_basic_use_case_usage Usage steps 166 * \subsection twi_basic_use_case_usage_code_writing Example code : Writing to a slave device 167 * Use in application C-file: 168 * \code 169 const uint8_t test_pattern[] = {0x55,0xA5,0x5A,0x77,0x99}; 170 171 twi_package_t packet_write = { 172 .addr = EEPROM_MEM_ADDR, // TWI slave memory address data 173 .addr_length = sizeof (uint16_t), // TWI slave memory address data size 174 .chip = EEPROM_BUS_ADDR, // TWI slave bus address 175 .buffer = (void *)test_pattern, // transfer data source buffer 176 .length = sizeof(test_pattern) // transfer data size (bytes) 177 }; 178 179 while (twi_master_write(&TWIM0, &packet_write) != TWI_SUCCESS); 180 \endcode 181 * 182 * \subsection twi_basic_use_case_usage_flow Workflow 183 * -# Prepare the data you want to send to the slave device: 184 * - \code const uint8_t test_pattern[] = {0x55,0xA5,0x5A,0x77,0x99}; \endcode 185 * -# Prepare a twi_package_t structure 186 * \code twi_package_t packet_write; \endcode 187 * Fill all the fields of the structure : 188 * - addr is the address in the slave device 189 * - addr_length is the size of the address in the slave (support for large TWI memory devices) 190 * - chip sets the 7 bit address of the slave device you want to communicate with 191 * - buffer is a pointer on the data to write to slave 192 * - length is the number of data to write 193 * 194 * -# Finally, call twi_master_write \code twi_master_write(&TWIM0, &packet_write); \endcode 195 * and optionally check its return value for TWI_SUCCESS. 196 * \subsection twi_basic_use_case_usage_code_reading Example code : Reading from a slave device 197 * Use in application C-file: 198 * \code 199 uint8_t data_received[10]; 200 201 twi_package_t packet_read = { 202 .addr = EEPROM_MEM_ADDR, // TWI slave memory address data 203 .addr_length = sizeof (uint16_t), // TWI slave memory address data size 204 .chip = EEPROM_BUS_ADDR, // TWI slave bus address 205 .buffer = data_received, // transfer data destination buffer 206 .length = 10 // transfer data size (bytes) 207 }; 208 // Perform a multi-byte read access then check the result. 209 if(twi_master_read(&TWIM0, &packet_read) == TWI_SUCCESS){ 210 //Check read content 211 if(data_received[0]==0x55) 212 do_something(); 213 } 214 \endcode 215 * 216 * \subsection twi_basic_use_case_usage_flow Workflow 217 * -# Prepare a data buffer that will receive the data from the slave device: 218 * \code uint8_t data_received[10]; \endcode 219 * -# Prepare a twi_package_t structure 220 * \code twi_package_t packet_read; \endcode 221 * Fill all the fields of the structure : 222 * - addr is the address in the slave device 223 * - addr_length is the size of the address in the slave (support for large TWI memory devices) 224 * - chip sets the 7 bit address of the slave device you want to communicate with 225 * - buffer is a pointer on the data buffer that will receive the data from the slave device 226 * - length is the number of data to read 227 * 228 * -# Finally, call twi_master_read \code twi_master_read(&TWIM0, &packet_read); \endcode 229 * and optionally check its return value for TWI_SUCCESS. 230 * the data read from the device are now in data_received. 231 */ 232 233 234 #endif /* TWI_MASTER_H_INCLUDED */ 235