PwmOut

Use the PwmOut interface to control the frequency and mark-to-space ratio of a digital pulse train.

API

 
 /* mbed Microcontroller Library
  * Copyright (c) 2006-2013 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 #ifndef MBED_PWMOUT_H
 #define MBED_PWMOUT_H
 
 #include "platform/platform.h"
 
 #if defined (DEVICE_PWMOUT) || defined(DOXYGEN_ONLY)
 #include "hal/pwmout_api.h"
 #include "platform/mbed_critical.h"
 
 namespace mbed {
 /** \addtogroup drivers */
 
 /** A pulse-width modulation digital output
  *
  * @note Synchronization level: Interrupt safe
  *
  * Example
  * @code
  * // Fade a led on.
  * #include "mbed.h"
  *
  * PwmOut led(LED1);
  *
  * int main() {
  * while(1) {
  * led = led + 0.01;
  * wait(0.2);
  * if(led == 1.0) {
  * led = 0;
  * }
  * }
  * }
  * @endcode
  * @ingroup drivers
  */
 class PwmOut {
 
 public:
 
  /** Create a PwmOut connected to the specified pin
  *
  * @param pin PwmOut pin to connect to
  */
  PwmOut(PinName pin) {
  pwmout_init(&_pwm, pin);
  }
 
  /** Set the ouput duty-cycle, specified as a percentage (float)
  *
  * @param value A floating-point value representing the output duty-cycle,
  * specified as a percentage. The value should lie between
  * 0.0f (representing on 0%) and 1.0f (representing on 100%).
  * Values outside this range will be saturated to 0.0f or 1.0f.
  */
  void write(float value) {
  pwmout_write(&_pwm, value);
  }
 
  /** Return the current output duty-cycle setting, measured as a percentage (float)
  *
  * @returns
  * A floating-point value representing the current duty-cycle being output on the pin,
  * measured as a percentage. The returned value will lie between
  * 0.0f (representing on 0%) and 1.0f (representing on 100%).
  *
  * @note
  * This value may not match exactly the value set by a previous write().
  */
  float read() {
  float val = pwmout_read(&_pwm);
  return val;
  }
 
  /** Set the PWM period, specified in seconds (float), keeping the duty cycle the same.
  *
  * @param seconds Change the period of a PWM signal in seconds (float) without modifying the duty cycle
  * @note
  * The resolution is currently in microseconds; periods smaller than this
  * will be set to zero.
  */
  void period(float seconds) {
  pwmout_period(&_pwm, seconds);
  }
 
  /** Set the PWM period, specified in milli-seconds (int), keeping the duty cycle the same.
  * @param ms Change the period of a PWM signal in milli-seconds without modifying the duty cycle
  */
  void period_ms(int ms) {
  pwmout_period_ms(&_pwm, ms);
  }
 
  /** Set the PWM period, specified in micro-seconds (int), keeping the duty cycle the same.
  * @param us Change the period of a PWM signal in micro-seconds without modifying the duty cycle
  */
  void period_us(int us) {
  pwmout_period_us(&_pwm, us);
  }
 
  /** Set the PWM pulsewidth, specified in seconds (float), keeping the period the same.
  * @param seconds Change the pulse width of a PWM signal specified in seconds (float)
  */
  void pulsewidth(float seconds) {
  pwmout_pulsewidth(&_pwm, seconds);
  }
 
  /** Set the PWM pulsewidth, specified in milli-seconds (int), keeping the period the same.
  * @param ms Change the pulse width of a PWM signal specified in milli-seconds
  */
  void pulsewidth_ms(int ms) {
  pwmout_pulsewidth_ms(&_pwm, ms);
  }
 
  /** Set the PWM pulsewidth, specified in micro-seconds (int), keeping the period the same.
  * @param us Change the pulse width of a PWM signal specified in micro-seconds
  */
  void pulsewidth_us(int us) {
  pwmout_pulsewidth_us(&_pwm, us);
  }
 
  /** A operator shorthand for write()
  * \sa PwmOut::write()
  */
  PwmOut& operator= (float value) {
  // Underlying call is thread safe
  write(value);
  return *this;
  }
 
  /** A operator shorthand for write()
  * \sa PwmOut::write()
  */
  // Underlying call is thread safe
  write(rhs.read());
  return *this;
  }
 
  /** An operator shorthand for read()
  * \sa PwmOut::read()
  */
  operator float() {
  // Underlying call is thread safe
  return read();
  }
 
 protected:
  pwmout_t _pwm;
 };
 
 } // namespace mbed
 
 #endif
 
 #endif
MBED_WEAK void core_util_critical_section_enter(void)
Definition: mbed_critical.c:56
void period(float seconds)
Definition: PwmOut.h:102
void period_us(int us)
Definition: PwmOut.h:120
void pulsewidth(float seconds)
Definition: PwmOut.h:129
float read()
Definition: PwmOut.h:88
void write(float value)
Definition: PwmOut.h:72
void period_ms(int ms)
Definition: PwmOut.h:111
void pulsewidth_us(int us)
Definition: PwmOut.h:147
PwmOut & operator=(float value)
Definition: PwmOut.h:156
void pulsewidth_ms(int ms)
Definition: PwmOut.h:138
Definition: PwmOut.h:51
PwmOut(PinName pin)
Definition: PwmOut.h:59
Definition: AnalogIn.h:27
MBED_WEAK void core_util_critical_section_exit(void)
Definition: mbed_critical.c:81

Hello World!

This code example uses the default period of 0.020s and ramps the duty cycle from 0% to 100% in increments of 10%.

 


#include "mbed.h"

PwmOut led(LED1);

int main() {
    // specify period first
    led.period(4.0f);      // 4 second period
    led.write(0.50f);      // 50% duty cycle, relative to period
    //led = 0.5f;          // shorthand for led.write()
    //led.pulsewidth(2);   // alternative to led.write, set duty cycle time in seconds
    while(1);
}

Details

The default period is 0.020s, and the default pulse width is 0.

The PwmOut interface can express the pulse train in many ways to fit different use cases. You can express the period and pulse width directly in units of seconds, millisecond or microseconds. You can also express the pulse width as a percentage of the the period.

Code Examples

Example one

This code example sets the period in seconds and the duty cycle as a percentage of the period in floating point (range: 0 to 1). The effect of this code snippet will be to blink LED2 over a four-second cycle, 50% on, for a pattern of two seconds on, two seconds off.

 


#include "mbed.h"

PwmOut led(LED2);

int main() {
    // specify period first, then everything else
    led.period(4.0f);  // 4 second period
    led.write(0.50f);  // 50% duty cycle
    while(1);          // led flashing
}

Example two

The following example does the same thing, but instead of specifying the duty cycle as a relative percentage of the period, it specifies it as an absolute value in seconds. In this case we have a four-second period and a two-second duty cycle, meaning the LED will be on for two seconds and off for two seconds.

 


#include "mbed.h"

PwmOut led(LED2);

int main() {
    // specify period first, then everything else
    led.period(4.0f);  // 4 second period
    led.pulsewidth(2); // 2 second pulse (on)
    while(1);          // led flashing
}


Example three

This code example is for an RC Servo. In RC Servos you set the position based on the PWM signal’s duty cycle or pulse width. This example code uses a period of 0.020s and increases the pulse width by 0.0001s on each pass. This will cause an increase of .5% of the servo’s range every .25s. In effect the servo will move 2% of its range per second, meaning after 50 seconds the servo will have gone from 0% to 100% of its range.