aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/source/gpio.rst106
1 files changed, 65 insertions, 41 deletions
diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst
index 64ad494..af1de20 100644
--- a/docs/source/gpio.rst
+++ b/docs/source/gpio.rst
@@ -7,18 +7,67 @@ Each LeafLabs board comes with ready-to-use General Purpose
Input/Output (GPIO) pins, which are numbered starting from zero.
These numbers are listed on your board's silkscreen, next to where the
pin is broken out to a header. Many pins may additionally be used for
-special features or peripheral functions.
+special features or interfacing with other hardware.
.. contents:: Contents
:local:
+.. _gpio-modes:
+
+GPIO Modes
+----------
+
+Each GPIO pin can be configured using :ref:`lang-pinmode` to behave in
+a number of ways: as a digital output pin, as an analog input pin,
+etc.
+
+A :ref:`WiringPinMode <lang-pinmode-wiringpinmode>` value specifies
+the complete set of possible configurations; not every pin can have
+all of these modes. For example, on the Maple, pin 15 may have mode
+``INPUT_ANALOG``, but not ``PWM``. See your board's :ref:`pin maps
+<gpio-pin-maps>` and its silkscreen for more information on what
+functionality is available on each pin.
+
+Function Reference
+------------------
+
+- :ref:`lang-pinmode`
+
+- :ref:`lang-digitalread`
+
+- :ref:`lang-digitalwrite`
+
+- :ref:`lang-analogread`
+
+- :ref:`lang-pwmwrite` (Maple's equivalent to ``analogWrite()``; see
+ :ref:`lang-analogwrite` for differences from the Arduino version).
+
+.. _gpio-ports:
+
+GPIO Ports
+----------
+
+Normally, you'll interact with pins using just their number (or a
+constant like :ref:`BOARD_LED_PIN <lang-board-values-led>` which
+stands for a number). However, behind the scenes, the STM32
+microcontroller on your board separates the pins into groups called
+*GPIO ports*. Each GPIO port is given a letter, so for example,
+there's GPIO port A, port B, and so on\ [#fnumports]_. The pins on a
+GPIO port are given *bit numbers*, which go from 0 to 15. In ST's
+documentation, a pin is given by the letter "P", followed by its port
+letter and bit number. For instance, "PA4" is GPIO port A, bit 4.
+
.. _gpio-pin-maps:
Pin Maps
--------
-The hardware documentation for your board lists each pin's
-capabilities, by pin number:
+Part of :ref:`Maple IDE's <ide>` job is to convert normal pin numbers
+into the corresponding GPIO port and bit when you call functions like
+:ref:`lang-pinmode`. It does this using a *pin map*, which lists the
+GPIO port and bit for each pin number. The GPIO documentation for
+your board includes its pin map, which also lists the other
+peripherals by pin number:
.. TODO [0.0.12] Native link
@@ -28,46 +77,15 @@ capabilities, by pin number:
.. * :ref:`Maple Native <maple-native-gpios>`
+.. _gpio-5v-tolerant:
+
The current and voltage limitations were determined using the STM32
datasheets. In particular, only some GPIO pins are **5V tolerant**,
which means that applying 5 volts to a pin and reading it as input or
allowing it to drain to ground will not damage that pin. Connecting a
-voltage higher than 3.3 V to a non-5 V tolerant pin may damage your
+voltage higher than 3.3V to a non-5V tolerant pin may damage your
board.
-.. _gpio-modes:
-
-GPIO Modes
-----------
-
-Each of the GPIO pins on a Maple board may be configured using
-pinMode() to behave in a number of ways: as a digital output pin,
-or as an analog input pin, etc., depending on the particular pin.
-
-A ``WiringPinMode`` value specifies the complete set of possible
-configurations; not every pin can have all of these modes. For
-example, on the Maple, pin 15 may have mode ``INPUT_ANALOG``, but not
-``PWM``. See your :ref:`board's pin maps <gpio-pin-maps>` and its
-silkscreen for more information on what functionality is available on
-each pin.
-
-.. doxygenenum:: WiringPinMode
-
-Function Reference
-------------------
-
-- :ref:`pinMode() <lang-pinmode>`
-
-- :ref:`digitalRead() <lang-digitalread>`
-
-- :ref:`digitalWrite() <lang-digitalwrite>`
-
-- :ref:`analogRead() <lang-analogread>`
-
-- :ref:`pwmWrite() <lang-pwmwrite>` (Maple's equivalent to
- ``analogWrite()``; see the :ref:`analogWrite() reference
- <lang-analogwrite>` for differences from the Arduino version).
-
.. _gpio-recommended-reading:
Recommended Reading
@@ -75,9 +93,15 @@ Recommended Reading
* ST Documentation for the STM32F103 series of microcontrollers:
- * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)
+ * `Reference Manual RM0008
+ <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_
+ (PDF); general, definitive resource for STM32F1 line.
+ * `Programming Manual PM0056
+ <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_
+ (PDF); assembly language and register reference.
- * `Programming Manual
- <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_
- (PDF; assembly language and register reference)
+.. rubric:: Footnotes
+.. [#fnumports] The total number of GPIO ports depends on what board
+ you have. For example, Maple Mini has three: ports A, B, and C.
+ Maple Native has seven: ports A through G.