docs/library/pyb.Pin: Add Pin.ALT constant.

chrismas9 · dpgeorge · commit 33ea400ce849 · 2022-07-29T12:16:32.000+10:00
Some Pin alternate functions are inputs, for example, timer capture and
break inputs.  In Pyb.Pin the only way to set alt mode is with Pin.AF_PP or
Pin.AF_OD.  It is not intuitive to use an output mode to configure an
input.  Pin.ALT is used in the machine.Pin class and works in pyb.Pin.

The examples are changed to use Pin.ALT because TIM2_CH3 can be a capture
input or pulse output.

Signed-off-by: Chris Mason &lt;c.mason@inchipdesign.com.au&gt;
diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst
@@ -97,6 +97,7 @@ Methods
         - ``Pin.IN`` - configure the pin for input;
         - ``Pin.OUT_PP`` - configure the pin for output, with push-pull control;
         - ``Pin.OUT_OD`` - configure the pin for output, with open-drain control;
+        - ``Pin.ALT`` - configure the pin for alternate function, input or output;
         - ``Pin.AF_PP`` - configure the pin for alternate function, push-pull;
         - ``Pin.AF_OD`` - configure the pin for alternate function, open-drain;
         - ``Pin.ANALOG`` - configure the pin for analog.
@@ -113,8 +114,8 @@ Methods
 
      - *value* if not None will set the port output value before enabling the pin.
 
-     - *alt* can be used when mode is ``Pin.AF_PP`` or ``Pin.AF_OD`` to set the
-       index or name of one of the alternate functions associated with a pin.
+     - *alt* can be used when mode is ``Pin.ALT`` , ``Pin.AF_PP`` or ``Pin.AF_OD`` to
+       set the index or name of one of the alternate functions associated with a pin.
        This arg was previously called *af* which can still be used if needed.
 
    Returns: ``None``.
@@ -177,6 +178,10 @@ Methods
 Constants
 ---------
 
+.. data:: Pin.ALT
+
+   initialise the pin to alternate-function mode for input or output
+
 .. data:: Pin.AF_OD
 
    initialise the pin to alternate-function mode with an open-drain drive
@@ -237,11 +242,11 @@ control is desired.
 
 To configure X3 to expose TIM2_CH3, you could use::
 
-   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, alt=pyb.Pin.AF1_TIM2)
+   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.ALT, alt=pyb.Pin.AF1_TIM2)
 
 or::
 
-   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, alt=1)
+   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.ALT, alt=1)
 
 Methods
 -------
