doc: Reorder KFile interface functions, add documentation.
[bertos.git] / boards / arduino / hw / hw_ntc.h
1 /**
2  * \file
3  * <!--
4  * This file is part of BeRTOS.
5  *
6  * Bertos is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
19  *
20  * As a special exception, you may use this file as part of a free software
21  * library without restriction.  Specifically, if other files instantiate
22  * templates or use macros or inline functions from this file, or you compile
23  * this file and link it with other files to produce an executable, this
24  * file does not by itself cause the resulting executable to be covered by
25  * the GNU General Public License.  This exception does not however
26  * invalidate any other reasons why the executable file might be covered by
27  * the GNU General Public License.
28  *
29  * Copyright 2008 Develer S.r.l. (http://www.develer.com/)
30  * All Rights Reserved.
31  * -->
32  *
33  * \brief NTC hardware-specific definition
34  *
35  * \author Francesco Sacchi <batt@develer.com>
36  *
37  * A NTC acts as a variable resistor, whose resistance changes as a
38  * function of the temperature it measures. To sample it correctly, it is
39  * usually parallelized and serialized with two fixed resistor. The following diagram shows
40  * what is the exact disposition of the components, as handled by this
41  * library:
42  *
43  *<pre>
44  *                 o Vref
45  *                 |
46  *                 |                               o Vref
47  *                 |                               |
48  *               -----                             |
49  *              |     |                        ---------
50  *              | Rser|                       |         |
51  *              |     |                       |         |
52  *               -----     -----              |   ADC   |
53  *                 | Vp   |     |             |         |
54  *      -----------|------| Amp |-------------|         |
55  *     |           |      |     |      Vadc   |         |
56  *   -----       -----     -----               ---------
57  *  |     |     |     |
58  *  | NTC |     | Rpar|
59  *  |     |     |     |
60  *   -----       -----
61  *     |           |
62  *     |           |
63  *   -----       -----
64  *    ---         ---
65  *</pre>
66  * Amp is an amplifier that amplify of AMP times the signal.
67  * If we indicate Rp as the parallel of NTC with Rpar, ADCBITS as the bits of the ad converter
68  * and ADCVAL as the result from the adc convertion (Not Vadc but just the value read
69  * from the adc register), after various calculation, the expression of Rp is:
70  *
71  *<pre>
72  *
73  *            ADCVAL * Rser
74  * Rp = ------------------------
75  *         ADCBITS
76  *      2         * AMP - ADCVAL
77  *</pre>
78  *
79  * And after that NTC obvisiously is:
80  *<pre>
81  *        Rpar * Rp
82  * NTC = ----------
83  *        Rpar - Rp
84  *</pre>
85  *
86  *
87  * The function ntc_hw_read() compute the resistence using these formulas above.
88  */
89
90 #ifndef HW_NTC_H
91 #define HW_NTC_H
92
93 #include "ntc_map.h"
94
95 #include <cfg/debug.h>
96
97 #include <drv/ntc.h>
98 #include <drv/adc.h>
99
100 #warning TODO:This is an example implementation, you must implement it!
101
102 extern const res_t      NTC_RSER[NTC_CNT];
103 extern const res_t      NTC_RPAR[NTC_CNT];
104 extern const amp_t      NTC_AMP[NTC_CNT];
105 extern const NtcHwInfo* NTC_INFO[NTC_CNT];
106
107
108 /*!
109  * Read the resistence of ntc device \a dev.
110  * Return the result in res_t type.
111  */
112 INLINE res_t ntc_hw_read(NtcDev dev)
113 {
114         ASSERT(dev < NTC_CNT);
115         // See above for formula explanation.
116         adcread_t adcval = adc_read((uint16_t)dev);
117         float rp = (adcval * NTC_RSER[dev] ) / ((1 << adc_bits()) * NTC_AMP[dev] - adcval);
118
119         //kprintf("Rp[%f], Rntc[%f]\n", rp/100, ((NTC_RPAR[dev] * rp) / (NTC_RPAR[dev] - rp)) / 100.0);
120
121         return ( (NTC_RPAR[dev] * rp) / (NTC_RPAR[dev] - rp) );
122 }
123
124
125 /*!
126  * Return the info (aka the table) associated with ntc device \a dev.
127  */
128 INLINE const NtcHwInfo* ntc_hw_getInfo(NtcDev dev)
129 {
130         return NTC_INFO[dev];
131 }
132
133 #define NTC_HW_INIT     do  { /* Implement me! */ } while(0)
134
135 #endif /* HW_NTC_H */