Merge remote branch 'leaf/master'

1 files changed, 21 insertions, 67 deletions

diff --git a/docs/source/pwm.rst b/docs/source/pwm.rst
index 178d103..1a8f4df 100644
--- a/docs/source/pwm.rst
+++ b/docs/source/pwm.rst
@@ -1,10 +1,9 @@
 .. _pwm:
 
-==============================
- Pulse-Width Modulation (PWM)
-==============================
+PWM
+===
 
-Pulse Width Modulation is a basic technique to create repeated square
+Pulse Width Modulation (PWM) is a basic technique to create repeated square
 waves (digital high/low voltage transitions) of user defined length
 and duty cycle. It can be used as a way to encode an "analog" signal
 on a single digital (high/low) line using the time between transitions
@@ -29,9 +28,9 @@ Note that unlike the Arduino, the Maple does not have PWM
 functionality on pin D10; all other pins are :ref:`compatible
 <compatibility>`.
 
-The following table shows which :ref:`timer <timers>` generates which
-PWM outputs. See the :ref:`pin mapping table <pin-mapping-mega-table>`
-to track down exactly which timer *channel* corresponds to each pin.
+The following table shows which timer can generate which PWM
+outputs. See the :ref:`pin mapping table <pin-mapping-mega-table>` to
+track down exactly which timer *channel* corresponds to each pin.
 
 .. _pwm-timer-table:
 
@@ -42,7 +41,7 @@ to track down exactly which timer *channel* corresponds to each pin.
    Timer1 | D6,D7,D8
    Timer2 | D0,D1,D2,D3
    Timer3 | D11,D12,D27,D28
-   Timer4 | D5,D9,D14,D24 
+   Timer4 | D5,D9,D14,D24
 
 Background
 ----------
@@ -66,12 +65,13 @@ The Maple has 16-bit PWM resolution, which means that the counter and
 variables can be as large as 65535, as opposed to 255 with 8-bit
 resolution. With a 72MHz clock rate, a PWM output could have maximum
 period of about one millisecond; using a :ref:`prescaler
-<pwm-prescaler>` (clock divider) in front of the counter can increase
-this maximum period.  Setting the :ref:`period <pwm-overflow>` to
-something other than the maximum value gives further control over the
-total length of the waveform.  However, this effectively limits the
-resolution with which the duty can be modified: the duty must be less
-than or equal to the period.
+<lang-hardwaretimer-setprescalefactor>` (clock divider) in front of
+the counter can increase this maximum period.  Setting the
+:ref:`period <lang-hardwaretimer-setperiod>` to something other than
+the maximum value gives further control over the total length of the
+waveform.  However, this effectively limits the resolution with which
+the duty can be modified: the duty must be less than or equal to the
+period.
 
 Here are some commonly used PWM configurations (note that servos are
 notoriously variable, especially the lower cost models):
@@ -94,58 +94,13 @@ notoriously variable, especially the lower cost models):
 Function Reference
 ------------------
 
-``pinMode(pin_num, PWM)``
-
-    This command is usually called from `setup()`_ to tell the
-    microcontroller that pin_num should be configured to PWM
-    output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN`` is
-    also available (see the list of :ref:`GPIO modes <gpio-modes>` for
-    more information).
-
-.. _pwm-pwmwrite:
-
-``pwmWrite(pin_num, value)``
-
-    This command sets the PWM duty. User code is expected to determine
-    and honor the maximum value (based on the configured period). As a
-    convenience, ``analogWrite`` is an alias for ``pwmWrite`` to ease
-    porting Arduino code, though period and duty will have to be
-    recalibrated (see :ref:`compatibility <compatibility>`).
-
-.. _pwm-overflow:
-
-``Timer1.setOverflow(overflow)``
-
-    This function sets the period ("reload" or "overflow") value for
-    an entire PWM timer bank. The value is 16bit (0 to 65535) and
-    determines the maximum value that can be written with
-    :ref:`pwmWrite() <pwm-pwmwrite>` corresponding to 100% duty
-    cycle. This also affects the PWM frequency: the higher reload is,
-    the lower the PWM frequency will be.
-
-    The PWM output pin starts HIGH, then the timer begins counting up
-    from zero (with frequency equal to 72MHz/:ref:`prescaler
-    <pwm-prescaler>`) until it hits the duty value, at which point it
-    drops to LOW.  The timer then continues counting up until it hits
-    the total period (set with this function), at which point the
-    cycle starts again.
-
-.. _pwm-prescaler:
-
-``Timer[1,2,3,4].setPrescaleFactor(prescale)``
-
-    Find the appropriate timer for a given PWM header using the table
-    :ref:`above <pwm-timer-table>`, then set the prescaler.  A
-    prescaler is a clock divider.  The timer will normally count with
-    frequency equal to the STM32's normal clock (72MHz); this
-    corresponds to setting ``prescale`` to 1 (which is the default).
-
-    If a longer frequency is desired, use a larger ``prescale`` value.
-    For instance, an 8MHz frequency can be achieved by setting
-    ``prescale`` to 9, since 72MHz / 9 = 8MHz.
-
-    This function is normally called once from, `setup()`_, but the
-    timer can be reconfigured with a new prescaler at any time.
+- :ref:`lang-pinmode`
+- :ref:`lang-pwmwrite`
+- :ref:`Timer API<lang-hardwaretimer>` (especially :ref:`setOverflow()
+  <lang-hardwaretimer-setoverflow>`, :ref:`setPrescaleFactor()
+  <lang-hardwaretimer-setprescalefactor>`, and :ref:`setPeriod()
+  <lang-hardwaretimer-setperiod>`).
+- :ref:`Timers reference <timers>`.
 
 Recommended Reading
 -------------------
@@ -159,6 +114,5 @@ Recommended Reading
 * `So You Want To Use PWM, Eh? <http://www.arcfn.com/2009/07/secrets-of-arduino-pwm.html>`_ at Non-Lexical Vocables
 * STMicro documentation for STM32F103RB microcontroller:
 
-  * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
   * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf)
   * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)