aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/gpio.rst
blob: c8448802ce6a6e56cfc9ad045d0c02735bec69e3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
.. _gpio:

GPIO
====

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 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
--------

Part of the library's 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:

* `Leaflabs Maple`_
* `Leaflabs Maple RET6`_
* `Leaflabs Maple Mini`_
* `Leaflabs Maple Native Beta`_

.. _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.3V to a non-5V tolerant pin may damage your
board.

.. _gpio-recommended-reading:

Recommended Reading
-------------------

* ST Documentation for the STM32F103 series of microcontrollers:

  * `Reference Manual RM0008
    <http://www.st.com/web/en/resource/technical/document/reference_manual/CD00171190.pdf>`_
    (PDF); general, definitive resource for STM32F1 line.
  * `Programming Manual PM0056
    <http://www.st.com/st-web-ui/static/active/en/resource/technical/document/programming_manual/CD00228163.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.