riot-ci/RIOT
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #11793 from MrKevinWeiss/pr/board/doc

Browse Source 
boards/doc: Add a guide to find physical board pins
This commit is contained in:
Kevin "Bear Puncher" Weiss 2019-07-09 10:43:13 +02:00 committed by GitHub
commit a5f65361b2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 53 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
boards/doc.txt
View File

@ -15,4 +15,57 @@
* configuration of a controller and some external devices such as sensors or
* radios. All aspects concerning configuration of GPIO pins, MCU clock and
* device drivers should go into this module.
*
Guide to board pinouts {#pinout_guide}
=====================================
The following are the steps to take to locate specific pinouts on boards.
This is useful when connecting external hardware to RIOT supported boards.
1. Check the [board documentation](http://doc.riot-os.org/group__boards.html)
to see if the pinout is available
2. If the pinout is not available or up to date check the following:
- `boards/<BOARD>/include/periph_conf.h` for board specific
peripherals such as UART or SPI pins
- `boards/<BOARD>/include/board.h` for GPIO specific pins such
as `LED0` or `BTN0`
- `boards/common/<COMMON_BOARD_OR_CPU>/include/periph_conf_common.h`
for shared pins that are the same for many different boards (board_common.h
or others will be available too)
- `boards/common/<COMMON_BOARD_OR_CPU>/include/<PERIPH_DECLARATION>`
also may contain specific periphirals such as
`PERIPH_DECLARATION = cfg_i2c1_pb8_pb9.h` which indicates I2C pins are on
pb8 and pb9
3. Once the needed pins are determined with either a port where
`PORTA = PORT_A = PA = 0` or `PORTB = PORT_B = PB = 1` and pin
number, such as `PA, 1`, correlate that to the board (the board
may either have the designators or search online to find which GPIO
corresponds to physical location on the board)
4. Match the `GPIO` with the specific pin and connect the wires
### Examples of finding pinouts
The following will be different examples of how to find pinouts
#### Finding pins of the I2C device 0 on samr21-xpro
1. The documentation says I2C is supported but does not say the pinout
2. Checking the pinout in `boards/samr21-xpro/include/periph_conf.h` the
`scl_pin = GPIO_PIN(PA, 17)` and the `sda_pin = GPIO_PIN(PA, 16)`
3. Since the board has the GPIO port and pin printed on the board the
physical location is `PA16` and `PA17`
#### Finding pins of the UART device 1 on nucleo-f103rb
_The dev number is only the location in the array and does not mean the
number of the peripheral_
1. The documentation says UART is supported but does not say the pinout
2. Checking the pinout in `boards/nucleo-f103rb/include/periph_conf.h` the
`rx_pin = GPIO_PIN(PORT_A, 10)`, the `tx_pin = GPIO_PIN(PORT_A, 9)` and the
`dev = USART1`, though device 1 can equal any USARTn number
3. Since the board does not have information on where these pins are
physically located it is recommended to search
[online](https://os.mbed.com/platforms/ST-Nucleo-F103RB/) for that board
4. After locating the physical layout the rx_pin can be found on CN9-1
using either `PA_10` or `UART1_RX` and the tx_pin can be found on CN5-1
using either `PA_9` or `UART1_TX`, it is recommended to use the GPIO pin as
sometimes the peripheral may be using an alternate pin
*/