Mbed OS Reference
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
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 "rtos/Mutex.h"
27
28#include <cmath>
29
30namespace 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 */
68class AnalogIn {
69
70public:
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 */
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 */
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
159protected:
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<rtos::Mutex> _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
An analog input, used for reading the voltage on a pin.
Definition: AnalogIn.h:68
void set_reference_voltage(float vref)
Sets this AnalogIn instance's reference voltage.
AnalogIn(const PinMap &pinmap, float vref=MBED_CONF_TARGET_DEFAULT_ADC_VREF)
Create an AnalogIn, connected to the specified pin.
unsigned short read_u16()
Read the input voltage, represented as an unsigned short in the range [0x0, 0xFFFF].
float read()
Read the input voltage, represented as a float in the range [0.0, 1.0].
float read_voltage()
Read the input voltage in volts.
float get_reference_voltage() const
Gets this AnalogIn instance's reference voltage.
AnalogIn(PinName pin, float vref=MBED_CONF_TARGET_DEFAULT_ADC_VREF)
Create an AnalogIn, connected to the specified pin.
void analogin_free(analogin_t *obj)
Release the analogin peripheral.
struct analogin_s analogin_t
Analogin hal structure.
Definition: analogin_api.h:34
Definition: pinmap.h:31
Utility class for creating and using a singleton.
Definition: SingletonPtr.h:88