Statistics
| Branch: | Tag: | Revision:

root / LUFA / Drivers / Peripheral / AVR8 / ADC_AVR8.h @ 978b99e5

History | View | Annotate | Download (17.9 KB)

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 ADC Peripheral Driver (AVR8)
33
 *
34
 *  On-chip Analogue-to-Digital converter (ADC) driver for supported U4, U6 and U7 model AVRs that contain an ADC
35
 *  peripheral internally.
36
 *
37
 *  \note This file should not be included directly. It is automatically included as needed by the ADC driver
38
 *        dispatch header located in LUFA/Drivers/Peripheral/ADC.h.
39
 */
40

    
41
/** \ingroup Group_ADC
42
 *  \defgroup Group_ADC_AVR8 ADC Peripheral Driver (AVR8)
43
 *
44
 *  \section Sec_ModDescription Module Description
45
 *  On-chip Analogue-to-Digital converter (ADC) driver for supported U4, U6 and U7 model AVRs that contain an ADC
46
 *  peripheral internally.
47
 *
48
 *  \note This file should not be included directly. It is automatically included as needed by the ADC driver
49
 *        dispatch header located in LUFA/Drivers/Peripheral/ADC.h.
50
 *
51
 *  \section Sec_ExampleUsage Example Usage
52
 *  The following snippet is an example of how this module may be used within a typical
53
 *  application.
54
 *
55
 *  \code
56
 *      // Initialize the ADC driver before first use
57
 *      ADC_Init(ADC_FREE_RUNNING | ADC_PRESCALE_32);
58
 *
59
 *      // Must setup the ADC channel to read beforehand
60
 *      ADC_SetupChannel(1);
61
 *
62
 *      // Perform a single conversion of the ADC channel 1
63
 *      ADC_GetChannelReading(ADC_REFERENCE_AVCC | ADC_RIGHT_ADJUSTED | ADC_CHANNEL1);
64
 *      printf("Conversion Result: %d\r\n", ADC_GetResult());
65
 *
66
 *      // Start reading ADC channel 1 in free running (continuous conversion) mode
67
 *      ADC_StartReading(ADC_REFERENCE_AVCC | ADC_RIGHT_ADJUSTED | ADC_CHANNEL1);
68
 *      for (;;)
69
 *      {
70
 *           while (!(ADC_IsReadingComplete())) {};
71
 *           printf("Conversion Result: %d\r\n", ADC_GetResult());
72
 *      }
73
 *  \endcode
74
 *
75
 *  @{
76
 */
77

    
78
#ifndef __ADC_AVR8_H__
79
#define __ADC_AVR8_H__
80

    
81
        /* Includes: */
82
                #include "../../../Common/Common.h"
83

    
84
        /* Enable C linkage for C++ Compilers: */
85
                #if defined(__cplusplus)
86
                        extern "C" {
87
                #endif
88

    
89
        /* Preprocessor Checks: */
90
                #if !defined(__INCLUDE_FROM_ADC_H)
91
                        #error Do not include this file directly. Include LUFA/Drivers/Peripheral/ADC.h instead.
92
                #endif
93

    
94
                #if !(defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB646__) || \
95
                      defined(__AVR_AT90USB1287__) || defined(__AVR_AT90USB647__) || \
96
                          defined(__AVR_ATmega16U4__)  || defined(__AVR_ATmega32U4__) || \
97
                          defined(__AVR_ATmega32U6__))
98
                        #error The ADC peripheral driver is not currently available for your selected microcontroller model.
99
                #endif
100

    
101
        /* Private Interface - For use in library only: */
102
        #if !defined(__DOXYGEN__)
103
                /* Macros: */
104
                        #define _ADC_GET_MUX_MASK2(y)           ADC_CHANNEL ## y
105
                        #define _ADC_GET_MUX_MASK(y)            _ADC_GET_MUX_MASK2(y)
106
        #endif
107
        
108
        /* Public Interface - May be used in end-application: */
109
                /* Macros: */
110
                        /** \name ADC Reference Configuration Masks */
111
                        //@{
112
                        /** Reference mask, for using the voltage present at the AVR's AREF pin for the ADC reference. */
113
                        #define ADC_REFERENCE_AREF              0
114

    
115
                        /** Reference mask, for using the voltage present at the AVR's AVCC pin for the ADC reference. */
116
                        #define ADC_REFERENCE_AVCC              (1 << REFS0)
117

    
118
                        /** Reference mask, for using the internally generated 2.56V reference voltage as the ADC reference. */
119
                        #define ADC_REFERENCE_INT2560MV         ((1 << REFS1) | (1 << REFS0))
120
                        //@}
121
                        
122
                        /** \name ADC Result Adjustment Configuration Masks */
123
                        //@{
124
                        /** Left-adjusts the 10-bit ADC result, so that the upper 8 bits of the value returned by the
125
                         *  \ref ADC_GetResult() macro contain the 8 most significant bits of the result.
126
                         */
127
                        #define ADC_LEFT_ADJUSTED               (1 << ADLAR)
128

    
129
                        /** Right-adjusts the 10-bit ADC result, so that the lower 8 bits of the value returned by the
130
                         *  \ref ADC_GetResult() macro contain the 8 least significant bits of the result.
131
                         */
132
                        #define ADC_RIGHT_ADJUSTED              (0 << ADLAR)
133
                        //@}
134

    
135
                        /** \name ADC Mode Configuration Masks */
136
                        //@{
137
                        /** Sets the ADC mode to free running, so that conversions take place continuously as fast as the ADC
138
                         *  is capable of at the given input clock speed.
139
                         */
140
                        #define ADC_FREE_RUNNING                (1 << ADATE)
141

    
142
                        /** Sets the ADC mode to single conversion, so that only a single conversion will take place before
143
                         *  the ADC returns to idle.
144
                         */
145
                        #define ADC_SINGLE_CONVERSION           (0 << ADATE)
146
                        //@}
147
                        
148
                        /** \name ADC Prescaler Configuration Masks */
149
                        //@{
150
                        /** Sets the ADC input clock to prescale by a factor of 2 the AVR's system clock. */
151
                        #define ADC_PRESCALE_2                  (1 << ADPS0)
152

    
153
                        /** Sets the ADC input clock to prescale by a factor of 4 the AVR's system clock. */
154
                        #define ADC_PRESCALE_4                  (1 << ADPS1)
155

    
156
                        /** Sets the ADC input clock to prescale by a factor of 8 the AVR's system clock. */
157
                        #define ADC_PRESCALE_8                  ((1 << ADPS0) | (1 << ADPS1))
158

    
159
                        /** Sets the ADC input clock to prescale by a factor of 16 the AVR's system clock. */
160
                        #define ADC_PRESCALE_16                 (1 << ADPS2)
161

    
162
                        /** Sets the ADC input clock to prescale by a factor of 32 the AVR's system clock. */
163
                        #define ADC_PRESCALE_32                 ((1 << ADPS2) | (1 << ADPS0))
164

    
165
                        /** Sets the ADC input clock to prescale by a factor of 64 the AVR's system clock. */
166
                        #define ADC_PRESCALE_64                 ((1 << ADPS2) | (1 << ADPS1))
167

    
168
                        /** Sets the ADC input clock to prescale by a factor of 128 the AVR's system clock. */
169
                        #define ADC_PRESCALE_128                ((1 << ADPS2) | (1 << ADPS1) | (1 << ADPS0))
170
                        //@}
171

    
172
                        /** \name ADC MUX Masks */
173
                        //@{
174
                        /** MUX mask define for the ADC0 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading(). */
175
                        #define ADC_CHANNEL0                    (0x00 << MUX0)
176

    
177
                        /** MUX mask define for the ADC1 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading(). */
178
                        #define ADC_CHANNEL1                    (0x01 << MUX0)
179

    
180
                        #if !(defined(__AVR_ATmega16U4__)  || defined(__AVR_ATmega32U4__) || defined(__DOXYGEN__))
181
                                /** MUX mask define for the ADC2 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading().
182
                                 *
183
                                 *  \note Not available on all AVR models.
184
                                 */
185
                                #define ADC_CHANNEL2                (0x02 << MUX0)
186

    
187
                                /** MUX mask define for the ADC3 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading().
188
                                 *
189
                                 *  \note Not available on all AVR models.
190
                                 */
191
                                #define ADC_CHANNEL3                (0x03 << MUX0)
192
                        #endif
193

    
194
                        /** MUX mask define for the ADC4 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading(). */
195
                        #define ADC_CHANNEL4                    (0x04 << MUX0)
196

    
197
                        /** MUX mask define for the ADC5 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading(). */
198
                        #define ADC_CHANNEL5                    (0x05 << MUX0)
199

    
200
                        /** MUX mask define for the ADC6 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading(). */
201
                        #define ADC_CHANNEL6                    (0x06 << MUX0)
202

    
203
                        /** MUX mask define for the ADC7 channel of the ADC. See \ref ADC_StartReading and \ref ADC_GetChannelReading. */
204
                        #define ADC_CHANNEL7                    (0x07 << MUX0)
205

    
206
                        /** MUX mask define for the internal 1.1V bandgap channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading(). */
207
                        #define ADC_1100MV_BANDGAP              (0x1E << MUX0)
208

    
209
                        #if (defined(__AVR_ATmega16U4__)  || defined(__AVR_ATmega32U4__) || defined(__DOXYGEN__))
210
                                /** MUX mask define for the ADC8 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading().
211
                                 *
212
                                 *  \note Not available on all AVR models.
213
                                 */
214
                                #define ADC_CHANNEL8                ((1 << 8) | (0x00 << MUX0))
215

    
216
                                /** MUX mask define for the ADC9 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading().
217
                                 *
218
                                 *  \note Not available on all AVR models.
219
                                 */
220
                                #define ADC_CHANNEL9                ((1 << 8) | (0x01 << MUX0))
221

    
222
                                /** MUX mask define for the ADC10 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading().
223
                                 *
224
                                 *  \note Not available on all AVR models.
225
                                 */
226
                                #define ADC_CHANNEL10               ((1 << 8) | (0x02 << MUX0))
227

    
228
                                /** MUX mask define for the ADC11 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading().
229
                                 *
230
                                 *  \note Not available on all AVR models.
231
                                 */
232
                                #define ADC_CHANNEL11               ((1 << 8) | (0x03 << MUX0))
233

    
234
                                /** MUX mask define for the ADC12 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading().
235
                                 *
236
                                 *  \note Not available on all AVR models.
237
                                 */
238
                                #define ADC_CHANNEL12               ((1 << 8) | (0x04 << MUX0))
239

    
240
                                /** MUX mask define for the ADC13 channel of the ADC. See \ref ADC_StartReading() and \ref ADC_GetChannelReading().
241
                                 *
242
                                 *  \note Not available on all AVR models.
243
                                 */
244
                                #define ADC_CHANNEL13               ((1 << 8) | (0x05 << MUX0))
245

    
246
                                /** MUX mask define for the internal temperature sensor channel of the ADC. See \ref ADC_StartReading() and
247
                                 *  \ref ADC_GetChannelReading().
248
                                 *
249
                                 *  \note Not available on all AVR models.
250
                                 */
251
                                #define ADC_INT_TEMP_SENS           ((1 << 8) | (0x07 << MUX0))
252
                        #endif
253

    
254
                        /** Retrieves the ADC MUX mask for the given ADC channel number.
255
                         *
256
                         *  \note This macro will only work correctly on channel numbers that are compile-time
257
                         *        constants defined by the preprocessor.
258
                         *
259
                         *  \param[in] Channel  Index of the ADC channel whose MUX mask is to be retrieved.
260
                         */
261
                        #define ADC_GET_CHANNEL_MASK(Channel)   _ADC_GET_MUX_MASK(Channel)
262
                        //@}
263

    
264
                /* Inline Functions: */
265
                        /** Configures the given ADC channel, ready for ADC conversions. This function sets the
266
                         *  associated port pin as an input and disables the digital portion of the I/O to reduce
267
                         *  power consumption.
268
                         *
269
                         *  \note This must only be called for ADC channels with are connected to a physical port
270
                         *        pin of the AVR, denoted by its special alternative function ADCx.
271
                         *        \n\n
272
                         *
273
                         *  \note The channel number must be specified as an integer, and <b>not</b> a \c ADC_CHANNEL* mask.
274
                         *
275
                         *  \param[in] ChannelIndex  ADC channel number to set up for conversions.
276
                         */
277
                        static inline void ADC_SetupChannel(const uint8_t ChannelIndex)
278
                        {
279
                                #if (defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB646__) || \
280
                                         defined(__AVR_AT90USB1287__) || defined(__AVR_AT90USB647__) || \
281
                                         defined(__AVR_ATmega32U6__))
282
                                DDRF  &= ~(1 << ChannelIndex);
283
                                DIDR0 |=  (1 << ChannelIndex);
284
                                #elif (defined(__AVR_ATmega16U4__) || defined(__AVR_ATmega32U4__))
285
                                if (ChannelIndex < 8)
286
                                {
287
                                        DDRF  &= ~(1 << ChannelIndex);
288
                                        DIDR0 |=  (1 << ChannelIndex);
289
                                }
290
                                else if (ChannelIndex == 8)
291
                                {
292
                                        DDRD  &= ~(1 << 4);
293
                                        DIDR2 |=  (1 << 0);
294
                                }
295
                                else if (ChannelIndex < 11)
296
                                {
297
                                        DDRD  &= ~(1 << (ChannelIndex - 3));
298
                                        DIDR2 |=  (1 << (ChannelIndex - 8));
299
                                }
300
                                else
301
                                {
302
                                        DDRB  &= ~(1 << (ChannelIndex - 7));
303
                                        DIDR2 |=  (1 << (ChannelIndex - 8));
304
                                }
305
                                #endif
306
                        }
307

    
308
                        /** De-configures the given ADC channel, re-enabling digital I/O mode instead of analog. This
309
                         *  function sets the associated port pin as an input and re-enabled the digital portion of
310
                         *  the I/O.
311
                         *
312
                         *  \note This must only be called for ADC channels with are connected to a physical port
313
                         *        pin of the AVR, denoted by its special alternative function ADCx.
314
                         *        \n\n
315
                         *
316
                         *  \note The channel number must be specified as an integer, and <b>not</b> a \c ADC_CHANNEL* mask.
317
                         *
318
                         *  \param[in] ChannelIndex  ADC channel number to set up for conversions.
319
                         */
320
                        static inline void ADC_DisableChannel(const uint8_t ChannelIndex)
321
                        {
322
                                #if (defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB646__) || \
323
                                         defined(__AVR_AT90USB1287__) || defined(__AVR_AT90USB647__) || \
324
                                         defined(__AVR_ATmega32U6__))
325
                                DDRF  &= ~(1 << ChannelIndex);
326
                                DIDR0 &= ~(1 << ChannelIndex);
327
                                #elif (defined(__AVR_ATmega16U4__) || defined(__AVR_ATmega32U4__))
328
                                if (ChannelIndex < 8)
329
                                {
330
                                        DDRF  &= ~(1 << ChannelIndex);
331
                                        DIDR0 &= ~(1 << ChannelIndex);
332
                                }
333
                                else if (ChannelIndex == 8)
334
                                {
335
                                        DDRD  &= ~(1 << 4);
336
                                        DIDR2 &= ~(1 << 0);
337
                                }
338
                                else if (ChannelIndex < 11)
339
                                {
340
                                        DDRD  &= ~(1 << (ChannelIndex - 3));
341
                                        DIDR2 &= ~(1 << (ChannelIndex - 8));
342
                                }
343
                                else
344
                                {
345
                                        DDRB  &= ~(1 << (ChannelIndex - 7));
346
                                        DIDR2 &= ~(1 << (ChannelIndex - 8));
347
                                }
348
                                #endif
349
                        }
350

    
351
                        /** Starts the reading of the given channel, but does not wait until the conversion has completed.
352
                         *  Once executed, the conversion status can be determined via the \ref ADC_IsReadingComplete() macro and
353
                         *  the result read via the \ref ADC_GetResult() macro.
354
                         *
355
                         *  If the ADC has been initialized in free running mode, calling this function once will begin the repeated
356
                         *  conversions. If the ADC is in single conversion mode (or the channel to convert from is to be changed),
357
                         *  this function must be called each time a conversion is to take place.
358
                         *
359
                         *  \param[in] MUXMask  ADC channel mask, reference mask and adjustment mask.
360
                         */
361
                        static inline void ADC_StartReading(const uint16_t MUXMask)
362
                        {
363
                                ADMUX = MUXMask;
364

    
365
                                #if (defined(__AVR_ATmega16U4__)  || defined(__AVR_ATmega32U4__) || defined(__DOXYGEN__))
366
                                if (MUXMask & (1 << 8))
367
                                  ADCSRB |=  (1 << MUX5);
368
                                else
369
                                  ADCSRB &= ~(1 << MUX5);
370
                                #endif
371

    
372
                                ADCSRA |= (1 << ADSC);
373
                        }
374

    
375
                        /** Indicates if the current ADC conversion is completed, or still in progress.
376
                         *
377
                         *  \return Boolean false if the reading is still taking place, or true if the conversion is
378
                         *          complete and ready to be read out with \ref ADC_GetResult().
379
                         */
380
                        static inline bool ADC_IsReadingComplete(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
381
                        static inline bool ADC_IsReadingComplete(void)
382
                        {
383
                                return ((ADCSRA & (1 << ADIF)) ? true : false);
384
                        }
385

    
386
                        /** Retrieves the conversion value of the last completed ADC conversion and clears the reading
387
                         *  completion flag.
388
                         *
389
                         *  \return The result of the last ADC conversion as an unsigned value.
390
                         */
391
                        static inline uint16_t ADC_GetResult(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
392
                        static inline uint16_t ADC_GetResult(void)
393
                        {
394
                                ADCSRA |= (1 << ADIF);
395
                                return ADC;
396
                        }
397

    
398
                        /** Performs a complete single reading from channel, including a polling spin-loop to wait for the
399
                         *  conversion to complete, and the returning of the converted value.
400
                         *
401
                         *  \note For free running mode, the automated conversions should be initialized with a single call
402
                         *        to \ref ADC_StartReading() to select the channel and begin the automated conversions, and
403
                         *        the results read directly from the \ref ADC_GetResult() instead to reduce overhead.
404
                         *
405
                         *  \param[in] MUXMask  Mask comprising of an ADC channel mask, reference mask and adjustment mask.
406
                         *
407
                         *  \return Converted ADC result for the given ADC channel.
408
                         */
409
                        static inline uint16_t ADC_GetChannelReading(const uint16_t MUXMask) ATTR_WARN_UNUSED_RESULT;
410
                        static inline uint16_t ADC_GetChannelReading(const uint16_t MUXMask)
411
                        {
412
                                ADC_StartReading(MUXMask);
413

    
414
                                while (!(ADC_IsReadingComplete()));
415

    
416
                                return ADC_GetResult();
417
                        }
418

    
419
                        /** Initializes the ADC, ready for conversions. This must be called before any other ADC operations.
420
                         *  The "mode" parameter should be a mask comprised of a conversion mode (free running or single) and
421
                         *  prescaler masks.
422
                         *
423
                         *  \param[in] Mode  Mask of ADC prescale and mode settings.
424
                         */
425
                        static inline void ADC_Init(uint8_t Mode) ATTR_ALWAYS_INLINE;
426
                        static inline void ADC_Init(uint8_t Mode)
427
                        {
428
                                ADCSRA = ((1 << ADEN) | Mode);
429
                        }
430

    
431
                        /** Turns off the ADC. If this is called, any further ADC operations will require a call to
432
                         *  \ref ADC_Init() before the ADC can be used again.
433
                         */
434
                        static inline void ADC_Disable(void) ATTR_ALWAYS_INLINE;
435
                        static inline void ADC_Disable(void)
436
                        {
437
                                ADCSRA = 0;
438
                        }
439

    
440
                        /** Indicates if the ADC is currently enabled.
441
                         *
442
                         *  \return Boolean \c true if the ADC subsystem is currently enabled, \c false otherwise.
443
                         */
444
                        static inline bool ADC_GetStatus(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
445
                        static inline bool ADC_GetStatus(void)
446
                        {
447
                                return ((ADCSRA & (1 << ADEN)) ? true : false);
448
                        }
449

    
450
        /* Disable C linkage for C++ Compilers: */
451
                #if defined(__cplusplus)
452
                        }
453
                #endif
454

    
455
#endif
456

    
457
/** @} */
458