granicus.if.org Git - esp-idf/blob - components/esp_adc_cal/esp_adc_cal.c

   1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 #include <stdint.h>
  16 #include "esp_types.h"
  17 #include "driver/adc.h"
  18 #include "soc/efuse_reg.h"
  19 #include "esp_err.h"
  20 #include "assert.h"
  21 #include "esp_adc_cal.h"
  22
  23 /* ----------------------------- Configuration ------------------------------ */
  24 #ifdef CONFIG_ADC_CAL_EFUSE_TP_ENABLE
  25 #define EFUSE_TP_ENABLED        1
  26 #else
  27 #define EFUSE_TP_ENABLED        0
  28 #endif
  29
  30 #ifdef CONFIG_ADC_CAL_EFUSE_VREF_ENABLE
  31 #define EFUSE_VREF_ENABLED      1
  32 #else
  33 #define EFUSE_VREF_ENABLED      0
  34 #endif
  35
  36 #ifdef CONFIG_ADC_CAL_LUT_ENABLE
  37 #define LUT_ENABLED             1
  38 #else
  39 #define LUT_ENABLED             0
  40 #endif
  41
  42 /* ESP32s with both Two Point Values and Vref burned into eFuse are required to
  43  * also also burn the EFUSE_BLK3_PART_RESERVE flag. A limited set of ESP32s
  44  * (not available through regular sales channel) DO NOT have the
  45  * EFUSE_BLK3_PART_RESERVE burned. Moreover, this set of ESP32s represents Vref
  46  * in Two's Complement format. If this is the case, modify the preprocessor
  47  * definitions below as follows...
  48  * #define CHECK_BLK3_FLAG         0        //Do not check BLK3 flag as it is not burned
  49  * #define VREF_FORMAT             1        //eFuse Vref is in Two's Complement format
  50  */
  51 #define CHECK_BLK3_FLAG         1
  52 #define VREF_FORMAT             0
  53
  54 /* ------------------------------ eFuse Access ----------------------------- */
  55 #define BLK3_RESERVED_REG               EFUSE_BLK0_RDATA3_REG
  56
  57 #define VREF_REG                        EFUSE_BLK0_RDATA4_REG
  58 #define VREF_MASK                       0x1F
  59 #define VREF_STEP_SIZE                  7
  60 #define VREF_OFFSET                     1100
  61
  62 #define TP_REG                          EFUSE_BLK3_RDATA3_REG
  63 #define TP_LOW1_OFFSET                  278
  64 #define TP_LOW2_OFFSET                  421
  65 #define TP_LOW_MASK                     0x7F
  66 #define TP_LOW_VOLTAGE                  150
  67 #define TP_HIGH1_OFFSET                 3265
  68 #define TP_HIGH2_OFFSET                 3406
  69 #define TP_HIGH_MASK                    0x1FF
  70 #define TP_HIGH_VOLTAGE                 850
  71 #define TP_STEP_SIZE                    4
  72
  73 /* ----------------------- Raw to Voltage Constants ------------------------- */
  74 #define LIN_COEFF_A_SCALE               65536
  75 #define LIN_COEFF_A_ROUND               (LIN_COEFF_A_SCALE/2)
  76
  77 #define LUT_VREF_LOW                    1000
  78 #define LUT_VREF_HIGH                   1200
  79 #define LUT_ADC_STEP_SIZE               64
  80 #define LUT_POINTS                      20
  81 #define LUT_LOW_THRESH                  2880
  82 #define LUT_HIGH_THRESH                 (LUT_LOW_THRESH + LUT_ADC_STEP_SIZE)
  83 #define ADC_12_BIT_RES                  4096
  84
  85 #define ADC_CAL_CHECK(cond, ret) ({                                         \
  86             if(!(cond)){                                                    \
  87                 return ret;                                                 \
  88             }                                                               \
  89 })
  90
  91 /* ------------------------ Characterization Constants ---------------------- */
  92 static const uint32_t adc1_tp_atten_scale[4] = {65504, 86975, 120389, 224310};
  93 static const uint32_t adc2_tp_atten_scale[4] = {65467, 86861, 120416, 224708};
  94 static const uint32_t adc1_tp_atten_offset[4] = {0, 1, 27, 54};
  95 static const uint32_t adc2_tp_atten_offset[4] = {0, 9, 26, 66};
  96
  97 static const uint32_t adc1_vref_atten_scale[4] = {57431, 76236, 105481, 196602};
  98 static const uint32_t adc2_vref_atten_scale[4] = {57236, 76175, 105678, 197170};
  99 static const uint32_t adc1_vref_atten_offset[4] = {75, 78, 107, 142};
 100 static const uint32_t adc2_vref_atten_offset[4] = {63, 66, 89, 128};
 101
 102 //20 Point lookup tables, covering ADC readings from 2880 to 4096, step size of 64
 103 static const uint32_t lut_adc1_low[LUT_POINTS] = {2240, 2297, 2352, 2405, 2457, 2512, 2564, 2616, 2664, 2709,
 104                                                   2754, 2795, 2832, 2868, 2903, 2937, 2969, 3000, 3030, 3060};
 105 static const uint32_t lut_adc1_high[LUT_POINTS] = {2667, 2706, 2745, 2780, 2813, 2844, 2873, 2901, 2928, 2956,
 106                                                    2982, 3006, 3032, 3059, 3084, 3110, 3135, 3160, 3184, 3209};
 107 static const uint32_t lut_adc2_low[LUT_POINTS] = {2238, 2293, 2347, 2399, 2451, 2507, 2561, 2613, 2662, 2710,
 108                                                   2754, 2792, 2831, 2869, 2904, 2937, 2968, 2999, 3029, 3059};
 109 static const uint32_t lut_adc2_high[LUT_POINTS] = {2657, 2698, 2738, 2774, 2807, 2838, 2867, 2894, 2921, 2946,
 110                                                    2971, 2996, 3020, 3043, 3067, 3092, 3116, 3139, 3162, 3185};
 111
 112 /* ----------------------- EFuse Access Functions --------------------------- */
 113 static bool check_efuse_vref()
 114 {
 115     //Check if Vref is burned in eFuse
 116     return (REG_GET_FIELD(VREF_REG, EFUSE_RD_ADC_VREF) != 0) ? true : false;
 117 }
 118
 119 static bool check_efuse_tp()
 120 {
 121     //Check if Two Point values are burned in eFuse
 122     if (CHECK_BLK3_FLAG && (REG_GET_FIELD(BLK3_RESERVED_REG, EFUSE_RD_BLK3_PART_RESERVE) == 0)) {
 123         return false;
 124     }
 125     //All TP cal values must be non zero
 126     if ((REG_GET_FIELD(TP_REG, EFUSE_RD_ADC1_TP_LOW) != 0) &&
 127         (REG_GET_FIELD(TP_REG, EFUSE_RD_ADC2_TP_LOW) != 0) &&
 128         (REG_GET_FIELD(TP_REG, EFUSE_RD_ADC1_TP_HIGH) != 0) &&
 129         (REG_GET_FIELD(TP_REG, EFUSE_RD_ADC2_TP_HIGH) != 0)) {
 130         return true;
 131     } else {
 132         return false;
 133     }
 134 }
 135
 136 static inline int decode_bits(uint32_t bits, uint32_t mask, bool is_twos_compl)
 137 {
 138     int ret;
 139     if (bits & (~(mask >> 1) & mask)) {      //Check sign bit (MSB of mask)
 140         //Negative
 141         if (is_twos_compl) {
 142             ret = -(((~bits) + 1) & (mask >> 1));   //2's complement
 143         } else {
 144             ret = -(bits & (mask >> 1));    //Sign-magnitude
 145         }
 146     } else {
 147         //Positive
 148         ret = bits & (mask >> 1);
 149     }
 150     return ret;
 151 }
 152
 153 static uint32_t read_efuse_vref()
 154 {
 155     //eFuse stores deviation from ideal reference voltage
 156     uint32_t ret = VREF_OFFSET;       //Ideal vref
 157     uint32_t bits = REG_GET_FIELD(VREF_REG, EFUSE_ADC_VREF);
 158     ret += decode_bits(bits, VREF_MASK, VREF_FORMAT) * VREF_STEP_SIZE;
 159     return ret;     //ADC Vref in mV
 160 }
 161
 162 static uint32_t read_efuse_tp_low(adc_unit_t adc_num)
 163 {
 164     //ADC reading at 150mV stored in two's complement format
 165     uint32_t ret;
 166     uint32_t bits;
 167
 168     if (adc_num == ADC_UNIT_1) {
 169         ret = TP_LOW1_OFFSET;
 170         bits = REG_GET_FIELD(TP_REG, EFUSE_RD_ADC1_TP_LOW);
 171     } else {
 172         ret = TP_LOW2_OFFSET;
 173         bits = REG_GET_FIELD(TP_REG, EFUSE_RD_ADC2_TP_LOW);
 174     }
 175     ret += decode_bits(bits, TP_LOW_MASK, true) * TP_STEP_SIZE;
 176     return ret;     //Reading of ADC at 150mV
 177 }
 178
 179 static uint32_t read_efuse_tp_high(adc_unit_t adc_num)
 180 {
 181     //ADC reading at 850mV stored in two's complement format
 182     uint32_t ret;
 183     uint32_t bits;
 184
 185     if (adc_num == ADC_UNIT_1) {
 186         ret = TP_HIGH1_OFFSET;
 187         bits = REG_GET_FIELD(TP_REG, EFUSE_RD_ADC1_TP_HIGH);
 188     } else {
 189         ret = TP_HIGH2_OFFSET;
 190         bits = REG_GET_FIELD(TP_REG, EFUSE_RD_ADC2_TP_HIGH);
 191     }
 192     ret += decode_bits(bits, TP_HIGH_MASK, true) * TP_STEP_SIZE;
 193     return ret;     //Reading of ADC at 850mV
 194 }
 195
 196 /* ----------------------- Characterization Functions ----------------------- */
 197 static void characterize_using_two_point(adc_unit_t adc_num,
 198                                          adc_atten_t atten,
 199                                          uint32_t high,
 200                                          uint32_t low,
 201                                          uint32_t *coeff_a,
 202                                          uint32_t *coeff_b)
 203 {
 204     const uint32_t *atten_scales;
 205     const uint32_t *atten_offsets;
 206
 207     if (adc_num == ADC_UNIT_1) { //Using ADC 1
 208         atten_scales = adc1_tp_atten_scale;
 209         atten_offsets = adc1_tp_atten_offset;
 210     } else {    //Using ADC 2
 211         atten_scales = adc2_tp_atten_scale;
 212         atten_offsets = adc2_tp_atten_offset;
 213     }
 214     //Characterize ADC-Voltage curve as y = (coeff_a * x) + coeff_b
 215     uint32_t delta_x = high - low;
 216     uint32_t delta_v = TP_HIGH_VOLTAGE - TP_LOW_VOLTAGE;
 217     //Where coeff_a = (delta_v/delta_x) * atten_scale
 218     *coeff_a = (delta_v * atten_scales[atten] + (delta_x / 2)) / delta_x;   //+(delta_x/2) for rounding
 219     //Where coeff_b = high_v - ((delta_v/delta_x) * high_x) + atten_offset
 220     *coeff_b = TP_HIGH_VOLTAGE - ((delta_v * high + (delta_x / 2)) / delta_x) + atten_offsets[atten];
 221 }
 222
 223 static void characterize_using_vref(adc_unit_t adc_num,
 224                                     adc_atten_t atten,
 225                                     uint32_t vref,
 226                                     uint32_t *coeff_a,
 227                                     uint32_t *coeff_b)
 228 {
 229     const uint32_t *atten_scales;
 230     const uint32_t *atten_offsets;
 231
 232     if (adc_num == ADC_UNIT_1) { //Using ADC 1
 233         atten_scales = adc1_vref_atten_scale;
 234         atten_offsets = adc1_vref_atten_offset;
 235     } else {    //Using ADC 2
 236         atten_scales = adc2_vref_atten_scale;
 237         atten_offsets = adc2_vref_atten_offset;
 238     }
 239     //Characterize ADC-Voltage curve as y = (coeff_a * x) + coeff_b
 240     //Where coeff_a = (vref/4096) * atten_scale
 241     *coeff_a = (vref * atten_scales[atten]) / (ADC_12_BIT_RES);
 242     *coeff_b = atten_offsets[atten];
 243 }
 244
 245 /* ------------------------ Conversion Functions --------------------------- */
 246 static uint32_t calculate_voltage_linear(uint32_t adc_reading, uint32_t coeff_a, uint32_t coeff_b)
 247 {
 248     //Where voltage = coeff_a * adc_reading + coeff_b
 249     return (((coeff_a * adc_reading) + LIN_COEFF_A_ROUND) / LIN_COEFF_A_SCALE) + coeff_b;
 250 }
 251
 252 //Only call when ADC reading is above threshold
 253 static uint32_t calculate_voltage_lut(uint32_t adc, uint32_t vref, const uint32_t *low_vref_curve, const uint32_t *high_vref_curve)
 254 {
 255     //Get index of lower bound points of LUT
 256     uint32_t i = (adc - LUT_LOW_THRESH) / LUT_ADC_STEP_SIZE;
 257
 258     //Let the X Axis be Vref, Y axis be ADC reading, and Z be voltage
 259     int x2dist = LUT_VREF_HIGH - vref;                 //(x2 - x)
 260     int x1dist = vref - LUT_VREF_LOW;                  //(x - x1)
 261     int y2dist = ((i + 1) * LUT_ADC_STEP_SIZE) + LUT_LOW_THRESH - adc;  //(y2 - y)
 262     int y1dist = adc - ((i * LUT_ADC_STEP_SIZE) + LUT_LOW_THRESH);        //(y - y1)
 263
 264     //For points for bilinear interpolation
 265     int q11 = low_vref_curve[i];                    //Lower bound point of low_vref_curve
 266     int q12 = low_vref_curve[i + 1];                //Upper bound point of low_vref_curve
 267     int q21 = high_vref_curve[i];                   //Lower bound point of high_vref_curve
 268     int q22 = high_vref_curve[i + 1];               //Upper bound point of high_vref_curve
 269
 270     //Bilinear interpolation
 271     //Where z = 1/((x2-x1)*(y2-y1)) * ( (q11*x2dist*y2dist) + (q21*x1dist*y2dist) + (q12*x2dist*y1dist) + (q22*x1dist*y1dist) )
 272     int voltage = (q11 * x2dist * y2dist) + (q21 * x1dist * y2dist) + (q12 * x2dist * y1dist) + (q22 * x1dist * y1dist);
 273     voltage += ((LUT_VREF_HIGH - LUT_VREF_LOW) * LUT_ADC_STEP_SIZE) / 2; //Integer division rounding
 274     voltage /= ((LUT_VREF_HIGH - LUT_VREF_LOW) * LUT_ADC_STEP_SIZE);    //Divide by ((x2-x1)*(y2-y1))
 275     return (uint32_t)voltage;
 276 }
 277
 278 static inline uint32_t interpolate_two_points(uint32_t y1, uint32_t y2, uint32_t x_step, uint32_t x)
 279 {
 280     //Interpolate between two points (x1,y1) (x2,y2) between 'lower' and 'upper' separated by 'step'
 281     return ((y1 * x_step) + (y2 * x) - (y1 * x) + (x_step / 2)) / x_step;
 282 }
 283
 284 /* ------------------------- Public API ------------------------------------- */
 285 esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t source)
 286 {
 287     if (source == ESP_ADC_CAL_VAL_EFUSE_TP) {
 288         return (check_efuse_tp()) ? ESP_OK : ESP_ERR_NOT_SUPPORTED;
 289     } else if (source == ESP_ADC_CAL_VAL_EFUSE_VREF) {
 290         return (check_efuse_vref()) ? ESP_OK : ESP_ERR_NOT_SUPPORTED;
 291     } else {
 292         return ESP_ERR_INVALID_ARG;
 293     }
 294 }
 295
 296 esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num,
 297                                              adc_atten_t atten,
 298                                              adc_bits_width_t bit_width,
 299                                              uint32_t default_vref,
 300                                              esp_adc_cal_characteristics_t *chars)
 301 {
 302     //Check parameters
 303     assert((adc_num == ADC_UNIT_1) || (adc_num == ADC_UNIT_2));
 304     assert(chars != NULL);
 305     assert(bit_width < ADC_WIDTH_MAX);
 306
 307     //Check eFuse if enabled to do so
 308     bool efuse_tp_present = check_efuse_tp();
 309     bool efuse_vref_present = check_efuse_vref();
 310     esp_adc_cal_value_t ret;
 311
 312     if (efuse_tp_present && EFUSE_TP_ENABLED) {
 313         //Characterize based on Two Point values
 314         uint32_t high = read_efuse_tp_high(adc_num);
 315         uint32_t low = read_efuse_tp_low(adc_num);
 316         characterize_using_two_point(adc_num, atten, high, low, &chars->coeff_a, &chars->coeff_b);
 317         ret = ESP_ADC_CAL_VAL_EFUSE_TP;
 318     } else if (efuse_vref_present && EFUSE_VREF_ENABLED) {
 319         //Characterize based on eFuse Vref
 320         uint32_t vref = read_efuse_vref();
 321         characterize_using_vref(adc_num, atten, vref, &chars->coeff_a, &chars->coeff_b);
 322         ret = ESP_ADC_CAL_VAL_EFUSE_VREF;
 323     } else {
 324         //Characterized based on default Vref
 325         characterize_using_vref(adc_num, atten, default_vref, &chars->coeff_a, &chars->coeff_b);
 326         ret = ESP_ADC_CAL_VAL_DEFAULT_VREF;
 327     }
 328
 329     //Initialized remaining fields
 330     chars->adc_num = adc_num;
 331     chars->atten = atten;
 332     chars->bit_width = bit_width;
 333     chars->vref = (EFUSE_VREF_ENABLED && efuse_vref_present) ? read_efuse_vref() : default_vref;
 334     //Initialize fields for lookup table if necessary
 335     if (LUT_ENABLED && atten == ADC_ATTEN_DB_11) {
 336         chars->low_curve = (adc_num == ADC_UNIT_1) ? lut_adc1_low : lut_adc2_low;
 337         chars->high_curve = (adc_num == ADC_UNIT_1) ? lut_adc1_high : lut_adc2_high;
 338     } else {
 339         chars->low_curve = NULL;
 340         chars->high_curve = NULL;
 341     }
 342     return ret;
 343 }
 344
 345 uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const esp_adc_cal_characteristics_t *chars)
 346 {
 347     assert(chars != NULL);
 348
 349     //Scale adc_rading if not 12 bits wide
 350     adc_reading = (adc_reading << (ADC_WIDTH_BIT_12 - chars->bit_width));
 351     if (adc_reading > ADC_12_BIT_RES - 1) {
 352         adc_reading = ADC_12_BIT_RES - 1;    //Set to 12bit res max
 353     }
 354
 355     if (LUT_ENABLED && (chars->atten == ADC_ATTEN_DB_11) && (adc_reading >= LUT_LOW_THRESH)) {  //Check if in non-linear region
 356         //Use lookup table to get voltage in non linear portion of ADC_ATTEN_DB_11
 357         uint32_t lut_voltage = calculate_voltage_lut(adc_reading, chars->vref, chars->low_curve, chars->high_curve);
 358         if (adc_reading <= LUT_HIGH_THRESH) {   //If ADC is transitioning from linear region to non-linear region
 359             //Linearly interpolate between linear voltage and lut voltage
 360             uint32_t linear_voltage = calculate_voltage_linear(adc_reading, chars->coeff_a, chars->coeff_b);
 361             return interpolate_two_points(linear_voltage, lut_voltage, LUT_ADC_STEP_SIZE, (adc_reading - LUT_LOW_THRESH));
 362         } else {
 363             return lut_voltage;
 364         }
 365     } else {
 366         return calculate_voltage_linear(adc_reading, chars->coeff_a, chars->coeff_b);
 367     }
 368 }
 369
 370 esp_err_t esp_adc_cal_get_voltage(adc_channel_t channel,
 371                                   const esp_adc_cal_characteristics_t *chars,
 372                                   uint32_t *voltage)
 373 {
 374     //Check parameters
 375     ADC_CAL_CHECK(chars != NULL, ESP_ERR_INVALID_ARG);
 376     ADC_CAL_CHECK(voltage != NULL, ESP_ERR_INVALID_ARG);
 377
 378     int adc_reading;
 379     if (chars->adc_num == ADC_UNIT_1) {
 380         //Check channel is valid on ADC1
 381         ADC_CAL_CHECK((adc1_channel_t)channel < ADC1_CHANNEL_MAX, ESP_ERR_INVALID_ARG);
 382         adc_reading = adc1_get_raw(channel);
 383     } else {
 384         //Check channel is valid on ADC2
 385         ADC_CAL_CHECK((adc2_channel_t)channel < ADC2_CHANNEL_MAX, ESP_ERR_INVALID_ARG);
 386         if (adc2_get_raw(channel, chars->bit_width, &adc_reading) != ESP_OK) {
 387             return ESP_ERR_TIMEOUT;     //Timed out waiting for ADC2
 388         }
 389     }
 390     *voltage = esp_adc_cal_raw_to_voltage((uint32_t)adc_reading, chars);
 391     return ESP_OK;
 392 }
 393
 394 /* ------------------------ Deprecated API --------------------------------- */
 395 void esp_adc_cal_get_characteristics(uint32_t vref,
 396                                      adc_atten_t atten,
 397                                      adc_bits_width_t bit_width,
 398                                      esp_adc_cal_characteristics_t *chars)
 399 {
 400     assert(chars != NULL);
 401     esp_adc_cal_characterize(ADC_UNIT_1, atten, bit_width, vref, chars);
 402 }
 403
 404 uint32_t adc1_to_voltage(adc1_channel_t channel, const esp_adc_cal_characteristics_t *chars)
 405 {
 406     assert(chars != NULL);
 407     uint32_t voltage = 0;
 408     esp_adc_cal_get_voltage((adc_channel_t)channel, chars, &voltage);
 409     return voltage;
 410 }
 411
 412