PwmOut.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef MBED_PWMOUT_H
00017 #define MBED_PWMOUT_H
00018 
00019 #include "platform/platform.h"
00020 
00021 #if defined (DEVICE_PWMOUT) || defined(DOXYGEN_ONLY)
00022 #include "hal/pwmout_api.h"
00023 #include "platform/mbed_critical.h"
00024 #include "platform/mbed_power_mgmt.h"
00025 
00026 namespace mbed {
00027 /** \addtogroup drivers */
00028 
00029 /** A pulse-width modulation digital output
00030  *
00031  * @note Synchronization level: Interrupt safe
00032  *
00033  * Example
00034  * @code
00035  * // Gradually change the intensity of the LED.
00036  * #include "mbed.h"
00037  *
00038  * PwmOut led(LED1);
00039  *
00040  * int main() {
00041  *     while(1) {
00042  *         led = led + 0.01;
00043  *         wait(0.2);
00044  *         if(led == 1.0) {
00045  *             led = 0;
00046  *         }
00047  *     }
00048  * }
00049  * @endcode
00050  * @ingroup drivers
00051  */
00052 class PwmOut {
00053 
00054 public:
00055 
00056     /** Create a PwmOut connected to the specified pin
00057      *
00058      *  @param pin PwmOut pin to connect to
00059      */
00060     PwmOut(PinName pin) : _deep_sleep_locked(false)
00061     {
00062         core_util_critical_section_enter();
00063         pwmout_init(&_pwm, pin);
00064         core_util_critical_section_exit();
00065     }
00066 
00067     ~PwmOut()
00068     {
00069         core_util_critical_section_enter();
00070         unlock_deep_sleep();
00071         core_util_critical_section_exit();
00072     }
00073 
00074     /** Set the output duty-cycle, specified as a percentage (float)
00075      *
00076      *  @param value A floating-point value representing the output duty-cycle,
00077      *    specified as a percentage. The value should lie between
00078      *    0.0f (representing on 0%) and 1.0f (representing on 100%).
00079      *    Values outside this range will be saturated to 0.0f or 1.0f.
00080      */
00081     void write(float value)
00082     {
00083         core_util_critical_section_enter();
00084         lock_deep_sleep();
00085         pwmout_write(&_pwm, value);
00086         core_util_critical_section_exit();
00087     }
00088 
00089     /** Return the current output duty-cycle setting, measured as a percentage (float)
00090      *
00091      *  @returns
00092      *    A floating-point value representing the current duty-cycle being output on the pin,
00093      *    measured as a percentage. The returned value will lie between
00094      *    0.0f (representing on 0%) and 1.0f (representing on 100%).
00095      *
00096      *  @note
00097      *  This value may not match exactly the value set by a previous write().
00098      */
00099     float read()
00100     {
00101         core_util_critical_section_enter();
00102         float val = pwmout_read(&_pwm);
00103         core_util_critical_section_exit();
00104         return val;
00105     }
00106 
00107     /** Set the PWM period, specified in seconds (float), keeping the duty cycle the same.
00108      *
00109      *  @param seconds Change the period of a PWM signal in seconds (float) without modifying the duty cycle
00110      *  @note
00111      *   The resolution is currently in microseconds; periods smaller than this
00112      *   will be set to zero.
00113      */
00114     void period(float seconds)
00115     {
00116         core_util_critical_section_enter();
00117         pwmout_period(&_pwm, seconds);
00118         core_util_critical_section_exit();
00119     }
00120 
00121     /** Set the PWM period, specified in milliseconds (int), keeping the duty cycle the same.
00122      *  @param ms Change the period of a PWM signal in milliseconds without modifying the duty cycle
00123      */
00124     void period_ms(int ms)
00125     {
00126         core_util_critical_section_enter();
00127         pwmout_period_ms(&_pwm, ms);
00128         core_util_critical_section_exit();
00129     }
00130 
00131     /** Set the PWM period, specified in microseconds (int), keeping the duty cycle the same.
00132      *  @param us Change the period of a PWM signal in microseconds without modifying the duty cycle
00133      */
00134     void period_us(int us)
00135     {
00136         core_util_critical_section_enter();
00137         pwmout_period_us(&_pwm, us);
00138         core_util_critical_section_exit();
00139     }
00140 
00141     /** Set the PWM pulsewidth, specified in seconds (float), keeping the period the same.
00142      *  @param seconds Change the pulse width of a PWM signal specified in seconds (float)
00143      */
00144     void pulsewidth(float seconds)
00145     {
00146         core_util_critical_section_enter();
00147         pwmout_pulsewidth(&_pwm, seconds);
00148         core_util_critical_section_exit();
00149     }
00150 
00151     /** Set the PWM pulsewidth, specified in milliseconds (int), keeping the period the same.
00152      *  @param ms Change the pulse width of a PWM signal specified in milliseconds
00153      */
00154     void pulsewidth_ms(int ms)
00155     {
00156         core_util_critical_section_enter();
00157         pwmout_pulsewidth_ms(&_pwm, ms);
00158         core_util_critical_section_exit();
00159     }
00160 
00161     /** Set the PWM pulsewidth, specified in microseconds (int), keeping the period the same.
00162      *  @param us Change the pulse width of a PWM signal specified in microseconds
00163      */
00164     void pulsewidth_us(int us)
00165     {
00166         core_util_critical_section_enter();
00167         pwmout_pulsewidth_us(&_pwm, us);
00168         core_util_critical_section_exit();
00169     }
00170 
00171     /** A operator shorthand for write()
00172      *  \sa PwmOut::write()
00173      */
00174     PwmOut &operator= (float value)
00175     {
00176         // Underlying call is thread safe
00177         write(value);
00178         return *this;
00179     }
00180 
00181     /** A operator shorthand for write()
00182      * \sa PwmOut::write()
00183      */
00184     PwmOut &operator= (PwmOut &rhs)
00185     {
00186         // Underlying call is thread safe
00187         write(rhs.read());
00188         return *this;
00189     }
00190 
00191     /** An operator shorthand for read()
00192      * \sa PwmOut::read()
00193      */
00194     operator float()
00195     {
00196         // Underlying call is thread safe
00197         return read();
00198     }
00199 
00200 #if !(DOXYGEN_ONLY)
00201 protected:
00202     /** Lock deep sleep only if it is not yet locked */
00203     void lock_deep_sleep()
00204     {
00205         if (_deep_sleep_locked == false) {
00206             sleep_manager_lock_deep_sleep();
00207             _deep_sleep_locked = true;
00208         }
00209     }
00210 
00211     /** Unlock deep sleep in case it is locked */
00212     void unlock_deep_sleep()
00213     {
00214         if (_deep_sleep_locked == true) {
00215             sleep_manager_unlock_deep_sleep();
00216             _deep_sleep_locked = false;
00217         }
00218     }
00219 
00220     pwmout_t _pwm;
00221     bool _deep_sleep_locked;
00222 #endif
00223 };
00224 
00225 } // namespace mbed
00226 
00227 #endif
00228 
00229 #endif