Mistake on this page?
Report an issue in GitHub or email us
AnalogIn.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2019 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 #ifndef MBED_ANALOGIN_H
18 #define MBED_ANALOGIN_H
19 
20 #include "platform/platform.h"
21 
22 #if DEVICE_ANALOGIN || defined(DOXYGEN_ONLY)
23 
24 #include "hal/analogin_api.h"
25 #include "platform/SingletonPtr.h"
26 #include "platform/PlatformMutex.h"
27 
28 #include <cmath>
29 
30 namespace mbed {
31 /** \defgroup mbed-os-public Public API */
32 
33 /** \defgroup drivers-public-api Drivers
34  * \ingroup mbed-os-public
35  */
36 
37 /** \defgroup drivers-public-api-gpio GPIO
38  * \ingroup drivers-public-api
39  */
40 
41 /**
42  * \defgroup drivers_AnalogIn AnalogIn class
43  * \ingroup drivers-public-api-gpio
44  * @{
45  */
46 
47 /** An analog input, used for reading the voltage on a pin
48  *
49  * @note Synchronization level: Thread safe
50  *
51  * Example:
52  * @code
53  * // Print messages when the AnalogIn is greater than 50%
54  *
55  * #include "mbed.h"
56  *
57  * AnalogIn temperature(p20);
58  *
59  * int main() {
60  * while(1) {
61  * if(temperature > 0.5) {
62  * printf("Too hot! (%f)", temperature.read());
63  * }
64  * }
65  * }
66  * @endcode
67  */
68 class AnalogIn {
69 
70 public:
71 
72  /** Create an AnalogIn, connected to the specified pin
73  *
74  * @param pinmap reference to structure which holds static pinmap.
75  * @param vref (optional) Reference voltage of this AnalogIn instance (defaults to target.default-adc-vref).
76  *
77  * @note An input voltage at or above the given vref value will produce a 1.0 result when `read` is called
78  */
79  AnalogIn(const PinMap &pinmap, float vref = MBED_CONF_TARGET_DEFAULT_ADC_VREF);
80  AnalogIn(const PinMap &&, float vref = MBED_CONF_TARGET_DEFAULT_ADC_VREF) = delete; // prevent passing of temporary objects
81 
82  /** Create an AnalogIn, connected to the specified pin
83  *
84  * @param pin AnalogIn pin to connect to
85  * @param vref (optional) Reference voltage of this AnalogIn instance (defaults to target.default-adc-vref).
86  *
87  * @note An input voltage at or above the given vref value will produce a 1.0 result when `read` is called
88  */
89  AnalogIn(PinName pin, float vref = MBED_CONF_TARGET_DEFAULT_ADC_VREF);
90 
91  /** Read the input voltage, represented as a float in the range [0.0, 1.0]
92  *
93  * @returns A floating-point value representing the current input voltage, measured as a percentage
94  */
95  float read();
96 
97  /** Read the input voltage, represented as an unsigned short in the range [0x0, 0xFFFF]
98  *
99  * @returns
100  * 16-bit unsigned short representing the current input voltage, normalized to a 16-bit value
101  */
102  unsigned short read_u16();
103 
104  /**
105  * Read the input voltage in volts. The output depends on the target board's
106  * ADC reference voltage (typically equal to supply voltage). The ADC reference voltage
107  * sets the maximum voltage the ADC can quantify (ie: ADC output == ADC_MAX_VALUE when Vin == Vref)
108  *
109  * The target's default ADC reference voltage is determined by the configuration
110  * option target.default-adc_vref. The reference voltage for a particular input
111  * can be manually specified by either the constructor or `AnalogIn::set_reference_voltage`.
112  *
113  * @returns A floating-point value representing the current input voltage, measured in volts.
114  */
115  float read_voltage();
116 
117  /**
118  * Sets this AnalogIn instance's reference voltage.
119  *
120  * The AnalogIn's reference voltage is used to scale the output when calling AnalogIn::read_volts
121  *
122  * @param[in] vref New ADC reference voltage for this AnalogIn instance.
123  */
124  void set_reference_voltage(float vref);
125 
126  /**
127  * Gets this AnalogIn instance's reference voltage.
128  *
129  * @returns A floating-point value representing this AnalogIn's reference voltage, measured in volts.
130  */
131  float get_reference_voltage() const;
132 
133  /** An operator shorthand for read()
134  *
135  * The float() operator can be used as a shorthand for read() to simplify common code sequences
136  *
137  * Example:
138  * @code
139  * float x = volume.read();
140  * float x = volume;
141  *
142  * if(volume.read() > 0.25) { ... }
143  * if(volume > 0.25) { ... }
144  * @endcode
145  */
146  operator float()
147  {
148  // Underlying call is thread safe
149  return read();
150  }
151 
152  virtual ~AnalogIn()
153  {
154  lock();
155  analogin_free(&_adc);
156  unlock();
157  }
158 
159 protected:
160 #if !defined(DOXYGEN_ONLY)
161  virtual void lock()
162  {
163  _mutex->lock();
164  }
165 
166  virtual void unlock()
167  {
168  _mutex->unlock();
169  }
170 
171  analogin_t _adc;
172  static SingletonPtr<PlatformMutex> _mutex;
173 
174  float _vref;
175 
176 #endif //!defined(DOXYGEN_ONLY)
177 
178 };
179 
180 /** @}*/
181 
182 } // namespace mbed
183 
184 #endif
185 
186 #endif
struct analogin_s analogin_t
Analogin hal structure.
Definition: analogin_api.h:34
float get_reference_voltage() const
Gets this AnalogIn instance&#39;s reference voltage.
float read_voltage()
Read the input voltage in volts.
An analog input, used for reading the voltage on a pin.
Definition: AnalogIn.h:68
float read()
Read the input voltage, represented as a float in the range [0.0, 1.0].
unsigned short read_u16()
Read the input voltage, represented as an unsigned short in the range [0x0, 0xFFFF].
AnalogIn(const PinMap &pinmap, float vref=MBED_CONF_TARGET_DEFAULT_ADC_VREF)
Create an AnalogIn, connected to the specified pin.
Definition: pinmap.h:31
void analogin_free(analogin_t *obj)
Release the analogin peripheral.
void set_reference_voltage(float vref)
Sets this AnalogIn instance&#39;s reference voltage.
Definition: ATHandler.h:46
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.