From c038ea0cc68bff18ce9ac338a283d2dd4cf29f1e Mon Sep 17 00:00:00 2001
From: chrismas9 <c.mason@inchipdesign.com.au>
Date: Sun, 26 Jun 2022 23:54:37 +1000
Subject: [PATCH] docs/library/pyb.Timer: Document how to use BKIN pin with
 example.

Document how to connect the Timer block BRK_IN to a physical Pin alternate
function.

Add an example of PWM Motor drive using complementary outputs with dead
time and break input to kill the PWM and generate a callback.

Signed-off-by: Chris Mason <c.mason@inchipdesign.com.au>
---
 docs/library/pyb.Timer.rst | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/library/pyb.Timer.rst b/docs/library/pyb.Timer.rst
index 53213666ba..1749efce2d 100644
--- a/docs/library/pyb.Timer.rst
+++ b/docs/library/pyb.Timer.rst
@@ -111,7 +111,9 @@ Methods
        the PWM when the ``BRK_IN`` input is asserted. The value of this
        argument determines if break is enabled and what the polarity is, and
        can be one of ``Timer.BRK_OFF``, ``Timer.BRK_LOW`` or
-       ``Timer.BRK_HIGH``.
+       ``Timer.BRK_HIGH``. To select the ``BRK_IN`` pin construct a Pin object with
+       ``mode=Pin.ALT, alt=Pin.AFn_TIMx``. The pin's GPIO input features are
+       available in alt mode - ``pull=`` , ``value()`` and ``irq()``.
 
     You must either specify freq or both of period and prescaler.
 
@@ -204,6 +206,17 @@ Methods
        ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.X2, pulse_width=8000)
        ch3 = timer.channel(3, pyb.Timer.PWM, pin=pyb.Pin.board.X3, pulse_width=16000)
 
+   PWM Motor Example with complementary outputs, dead time, break input and break callback::
+
+       from pyb import Timer
+       from machine import Pin # machine.Pin supports alt mode and irq on the same pin.
+       pin_t8_1 = Pin(Pin.board.Y1, mode=Pin.ALT, af=Pin.AF3_TIM8)   # Pin PC6, TIM8_CH1
+       pin_t8_1n = Pin(Pin.board.X8, mode=Pin.ALT, af=Pin.AF3_TIM8)  # Pin PA7, TIM8_CH1N
+       pin_bkin = Pin(Pin.board.X7, mode=Pin.ALT, af=Pin.AF3_TIM8)   # Pin PA6, TIM8_BKIN
+       pin_bkin.irq(handler=break_callabck, trigger=Pin.IRQ_FALLING)
+       timer = pyb.Timer(8, freq=1000, deadtime=1008, brk=Timer.BRK_LOW)
+       ch1 = timer.channel(1, pyb.Timer.PWM, pulse_width_percent=30)
+
 .. method:: Timer.counter([value])
 
    Get or set the timer counter.