modules/hardware/adc/adc.h

   1 /*
   2  *  Copyright Droids Corporation, Microb Technology, Eirbot (2005)
   3  *
   4  *  This program is free software; you can redistribute it and/or modify
   5  *  it under the terms of the GNU General Public License as published by
   6  *  the Free Software Foundation; either version 2 of the License, or
   7  *  (at your option) any later version.
   8  *
   9  *  This program is distributed in the hope that it will be useful,
  10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *  GNU General Public License for more details.
  13  *
  14  *  You should have received a copy of the GNU General Public License
  15  *  along with this program; if not, write to the Free Software
  16  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  17  *
  18  *  Revision : $Id: adc.h,v 1.7.4.3 2007-09-06 08:15:37 zer0 Exp $
  19  *
  20  */
  21 /** \file adc.h
  22  *  \brief Interface of the ADC Module
  23  *
  24  *  \todo some ATtiny support to add
  25  *
  26  *  \test nothing done
  27  *
  28  * This module provides access to the built-in ADC unit of the AVR
  29  * uCs.
  30  */
  31
  32
  33 #ifndef _ADC_H_
  34 #define _ADC_H_
  35
  36 #include <aversive.h>
  37
  38 #include <adc_archs.h>
  39 #include <adc_config.h>
  40
  41 /*
  42  * You must always specify a MUX and a REF flag.
  43  * MUX selection flags :
  44  *
  45  * A lot of them exist, for more, see the capabilities of your uC in
  46  * the datasheet. Typical examples:
  47  *
  48  *  MUX_ADC0             : selects input 0
  49  *  MUX_ADC0_ADC1        : selects the electrical signal ADC0-ADC1
  50  *  MUX_ADC0_ADC1_GAIN10 : selects the electrical signal (ADC0-ADC1) *10
  51  *  ...
  52  *  MUX_VBG              : selects the internal bandgap reference
  53  *  MUX_GND              : selects the GND pin (0V)
  54  *
  55  * See your Datasheet, and adc_archs.h for more info.
  56  *
  57  *
  58  *
  59  * Reference flags : use one of these four :
  60  *
  61  *  ADC_REF_AREF  : a reference must be connected to the AREF pin :
  62  *                  default
  63  *  ADC_REF_AVCC  : using AVCC as reference : recommended for default !!!
  64  *  ADC_REF_VREF  : using the internal reference
  65  *  ADC_REF_VREF2 : internal ref, with options. Beware, this does not
  66  *                  work on all devices, see your Datasheet !!
  67  *
  68  * For some controllers (actually only ATtiny25-45-85) you can specify
  69  * more options, just use (1<<REFS2)|(1<<REFS0)
  70  *
  71  * YOU NEED TO SPECIFY THIS VALUE FOR EACH CONVERSION CONFIGURATION !!!!!
  72  */
  73
  74
  75 /**
  76  * Set this flag for using interruptions instead of polling.
  77  * If you use this, do not call the adc_get_value() function !
  78  */
  79 #define ADC_MODE_INT        0x0200
  80
  81 /**
  82  * Flag for triggered mode.
  83  */
  84 #define ADC_MODE_TRIGGERED  0x0400
  85
  86 /*
  87  * Using one of this flags selects in which form the result is given
  88  *
  89  * These flags select the output format. The signed options are only
  90  * for the differential measurement ! Don't use them for single ended
  91  * measurements, or the results will be wrong.
  92  *
  93  * ADC_MODE_10_BITS : This format will give you a result between 0 and
  94  *                    1023 This format is default, you do not need to
  95  *                    specify the flag.
  96
  97  * ADC_MODE_16_BITS : This will use all the span of the uint16_t (or
  98  *                    int16_t for a differential conversion) beware !!
  99  *                    Cast your result in the correct type since the
 100  *                    type depends of the type of channel you select.
 101  */
 102 #define ADC_MODE_10_BITS            0
 103 #define ADC_MODE_16_BITS            ADLAR_MASK_IN_CONFIG
 104
 105 /**
 106  * this flag is used internally of the module, use it only if you set
 107  * manually a differential channel.
 108  */
 109 #define ADC_RESULT_SIGNED           0x1000
 110
 111
 112 /**
 113  * This specifies a conversion with no config (uses the previous
 114  * parameters) always use this flag alone !!
 115  */
 116 #define ADC_NO_CONFIG            0xFFFF
 117
 118
 119 /**************/
 120
 121
 122 /**
 123  * Initialisation of ADC internal registers
 124  * Can be called for a wake up after a shutdown command
 125  */
 126 void adc_init(void);
 127
 128 /**
 129  * Shut down the ADC, for power consumption
 130  */
 131 void adc_shutdown(void);
 132
 133
 134 /**
 135  * Register callback event. The parameter function is called when the
 136  * conversion is finished.
 137  */
 138 void adc_register_event(void (*f)(int16_t));
 139
 140
 141
 142 /**
 143  * Launch a conversion : this function launches a conversion with the
 144  * specified configuration.  The conversion_config is casted to an
 145  * int.
 146 */
 147 void adc_launch(uint16_t conversion_config);
 148
 149
 150 /**
 151  * This function gets an ADC value. If a conversion has been
 152  * previously started, with EXACTLY the same config (or specifying
 153  * ADC_NO_CONFIG) then it waits for it to finish. Else it launches a
 154  * new one with the given config, and polls the result.
 155  *
 156  * This function should not be used if you use interrupts, but only
 157  * can be used with triggered (or free run mode)
 158  */
 159 int16_t adc_get_value(uint16_t conversion_config);
 160
 161
 162 /**
 163  * Just a int32_t version for compatibility with control_system
 164  * function prototypes.
 165  */
 166 extern int32_t adc_get_value32(void * conversion_config);
 167
 168
 169
 170 #endif // _ADC_H_