docs/samd: Add documentation for the samd port.

Includes a general overview, a quickref, pinout tables, and the beginnings
of a tutorial.

5 files changed, 1491 insertions, 0 deletions

diff --git a/docs/samd/general.rst b/docs/samd/general.rst
new file mode 100644
index 000000000..66e6d2a31
--- /dev/null
+++ b/docs/samd/general.rst
@@ -0,0 +1,88 @@
+.. _samd_general:
+
+General information about the SAMD port
+=======================================
+
+The SAMD21/SAMD51 MCU family is a high performance family of devices made by MicroChip.
+The SAMD21 devices are based on an ARM M0+ core, the SAMD51 device on ARM Cortex M4 core.
+They provide many on-chip I/O units for building small to medium sized devices.
+
+Multitude of boards
+-------------------
+
+There is a multitude of modules and boards from different sources which carry
+an SAMD21/SAMD51 chip.  MicroPython aims to provide a generic port which runs on
+as many boards/modules as possible, but there may be limitations.  The
+Adafruit ItsyBitsy M0 Express, Adafruit Feather M4 Express and the Adafruit ItsyBitsy M4 Express
+development boards are taken as reference for the port (for example, testing is performed on them).
+For any board you are using please make sure you have a data sheet, schematics
+and other reference materials so you can look up any board-specific functions.
+
+The following boards are at the moment supported by the port:
+
+- ADAFRUIT FEATHER M0 EXPRESS
+- ADAFRUIT FEATHER M4 EXPRESS
+- ADAFRUIT ITSYBITSY M0 EXPRESS
+- ADAFRUIT ITSYBITSY M4 EXPRESS
+- ADAFRUIT TRINKET M0
+- MINISAM M4
+- SAMD21 XPLAINED PRO
+- SEEED WIO TERMINAL
+- SEEED XIAO
+
+To make a generic SAMD port and support as many boards as possible the
+following design and implementation decision were made:
+
+* GPIO pin numbering is based on the board numbering.
+  Please have the manual/pin diagram of your board at hand
+  to find correspondence between your board pins and actual SAMD21/SAMD51 pins.
+  For the boards listed above, the relation between the board pin number and
+  the GPIO number can be found at :ref:`samd_pinout`.
+* The pins that can be used by MicroPython are limited to those listed
+  in the board definition files.
+
+Technical specifications and SoC data sheets
+--------------------------------------------
+
+The data sheets and other reference material for SAMD21/SAMD51 chip are available
+from the vendor site: https://www.microchip.com/en-us/products/microcontrollers-and-microprocessors/32-bit-mcus/sam-32-bit-mcus
+They are the primary reference for the chip technical specifications, capabilities,
+operating modes, internal functioning, etc.
+
+For your convenience, a few technical specifications are provided below:
+
+SAMD21:
+
+* Architecture: ARM Cortex M0+
+* CPU frequency: up to 48MHz
+* Total RAM available: up to 32 kB (see table)
+* Internal FlashROM: up to 256 kB
+  Some boards provide additional external SPI flash.
+* GPIO: up to 52 (GPIOs are multiplexed with other functions, including
+  external FlashROM, UART, etc.)
+* UART: up to 6 serial devices, which can used for UART, SPI or I2C.
+* I2S: 1 I2S interfaces
+* ADC: One 12-bit SAR ADC converter with 16 channels.
+* Programming: using BootROM bootloader from USB.
+
+SAMD51:
+
+* Architecture: ARM Cortex M4
+* CPU frequency: up to 120MHz
+* Total RAM available: up to 256 kB
+* Internal FlashROM: up to 1 MB
+  Some boards provide additional external SPI flash.
+* GPIO: up to 99 (GPIOs are multiplexed with other functions, including
+  external FlashROM, UART, etc.)
+* UART: up to 8 serial devices, which can used for UART, SPI or I2C.
+* I2S: 1 I2S interfaces
+* ADC: Dual 12-bit SAR ADC converter with 16 channels.
+* Programming: using BootROM bootloader from USB.
+
+
+For more information see the excellent SAMD21/SAMD51 data sheets or reference manuals.
+
+At the moment, the SAM21 port of MicroPython requires 256kB flash, of which 64kB is used
+for a small file system. The SAM51 port requires 512 kB of flash, of which all flash beyond
+384kB is used for a file system. Some boards have additional flash memory, which can be used
+as additional file space.
diff --git a/docs/samd/img/itsybitsy_m4_express.jpg b/docs/samd/img/itsybitsy_m4_express.jpg
new file mode 100644
index 000000000..ea18b5c38
--- /dev/null
+++ b/docs/samd/img/itsybitsy_m4_express.jpg
diff --git a/docs/samd/pinout.rst b/docs/samd/pinout.rst
new file mode 100644
index 000000000..7e8d7ad90
--- /dev/null
+++ b/docs/samd/pinout.rst
@@ -0,0 +1,850 @@
+.. _samd_pinout:
+
+Pinout for the SAMD machine modules
+===================================
+
+The assignment of device functions to pins is very flexible. The same function may be used
+at different pins. The representation of the assignment choices are given by a table,
+which is a subset of the MCU's Pin MUX table and is specific to each board, as the
+available pin set varies. The structure of the table is the same for each board, but
+the set of rows is different.
+
+.. _samd21_pinout_table:
+
+Adafruit ItsyBitsy M0 Express pin assignment table
+--------------------------------------------------
+
+=== ==== ============ ==== ==== ====== ====== ====== ======
+Pin GPIO Pin name     IRQ  ADC  Serial Serial TCC/TC TCC/TC
+=== ==== ============ ==== ==== ====== ====== ====== ======
+  0 PA11           D0  11   19    0/3    2/3   1/1    0/3
+  1 PA10           D1  10   18    0/2    2/2   1/0    0/2
+  2 PA14           D2  14    -    2/2    4/2   3/0    0/4
+  3 PA09           D3   9   17    0/1    2/1   0/1    1/3
+  4 PA08           D4   -   16    0/0    2/0   0/0    1/2
+  5 PA15           D5  15    -    2/3    4/3   3/1    0/5
+  7 PA21           D7   5    -    5/3    3/3   7/1    0/7
+  9 PA07           D9   7    7     -     0/3   1/1     -
+ 10 PA18          D10   2    -    1/2    3/2   3/0    0/2
+ 11 PA16          D11   0    -    1/0    3/0   2/0    0/6
+ 12 PA19          D12   3    -    1/3    3/3   3/1    0/3
+ 13 PA17          D13   1    -    1/1    3/1   2/1    0/7
+ 14 PA02           A0   2    0     -      -     -      -
+ 15 PB08           A1   8    2     -     4/0   4/0     -
+ 16 PB09           A2   9    3     -     4/1   4/1     -
+ 17 PA04           A3   4    4     -     0/0   0/0     -
+ 18 PA05           A4   5    5     -     0/1   0/1     -
+ 19 PB02           A5   2    -     -     5/0   6/0     -
+ 20 PA22          SDA   6    -    3/0    5/0   4/0    0/4
+ 21 PA23          SCL   7    -    3/1    5/1   4/1    0/5
+ 22 PB10         MOSI  10    -     -     4/2   5/0    0/4
+ 23 PA12         MISO  12    -    2/0    4/0   2/0    0/6
+ 24 PB11          SCK  11    -     -     4/3   5/1    0/5
+ 25 PA00  DOTSTAR_CLK   0    -     -     1/0   2/0     -
+ 26 PA01 DOTSTAR_DATA   1    -     -     1/1   2/1     -
+ 27 PB22   FLASH_MOSI   6    -     -     5/2   7/0     -
+ 28 PB03   FLASH_MISO   3    -     -     5/1   6/1     -
+ 29 PB23    FLASH_SCK   7    -     -     5/3   7/1     -
+=== ==== ============ ==== ==== ====== ====== ====== ======
+
+
+Description of the columns:
+
+- *Pin* - The number that is expected at ``machine.Pin(n)``, if the pin is given
+  as a number. This is NOT the GPIO number, but the board pin number, as
+  given in the board specific definition file.
+- *GPIO* - The GPIO number.
+- *Pin Name* - The name of a Pin which is expected argument to ``machine.Pin("name")``.
+- *IRQ* - The IRQ number assigned to that GPIO, used internally by ``Pin.irq()``. When
+  using ``Pin.irq()``, different pins must use different IRQs
+- *ADC* - The ADC channel assigned to the pin. When using ADC, different pins must
+  not use the same ADC channel.
+- *Serial* - Two columns with optional Serial signal assignments. Both may be used.
+  The cell content is device #/pad #. The pad # is the respective internal
+  signal of that serial device. Details below.
+- *TCC/TC* - Two columns with assignments of the TCC modules for PWM.
+  The cell content is device #/output #. For PWM, devices 0, 1, and 2
+  are used. The TC device pair 3/4 is used for ``ticks_us()``.
+
+SAMD21 UART assignments
+```````````````````````
+The UART devices and signals must be chosen according to the following rules:
+
+- The TX signal must be at a Pin with pad numbers 2 or 0, like Pin 1 with serial
+  device 0 or 2.
+- The RX pin may be assigned to one of the other pads.
+
+Examples for Adafruit ItsyBitsy M0 Express:
+
+- uart 0 at pins 0/1  This is the default UART at the RX/TX labelled pins
+- uart 1 at pins 12/10
+- uart 2 at pins 0/1
+- uart 3 at pins 11/13
+- uart 4 at pins 2/5
+- uart 5 at pins SCL/SDA
+
+or other combinations.
+
+SAMD21 I2C assignments
+``````````````````````
+The I2C devices and signals must be chosen according to the following rules:
+
+- The SDA signal must be at a Pin with pad numbers 0.
+- The SCL signal must be at a Pin with pad numbers 1.
+
+Examples for Adafruit ItsyBitsy M0 Express:
+
+- I2C 0 at Pin A3/A4
+- I2C 1 at pins 11/13
+- I2C 2 at the pins 4/3
+- I2C 3 at the pins SDA/SCL This is the default I2C device at the SDA/SCl labelled pin
+- I2C 4 at the pins A1/A2
+- I2C 5 at the pins SDA/SCL,
+
+or other combinations.
+
+SAMD21 SPI assignments
+``````````````````````
+The I2C devices and signals must be chosen according to the following rules:
+
+- The following pad number pairs are suitable for MOSI/SCK: 0/1, 2/3, 3/1, and 0/3.
+- The MISO signal must be at a Pin with a different pad number than MOSI or SCK.
+
+Examples for Adafruit ItsyBitsy M0 Express:
+
+- SPI 0 at pins 0/4/1
+- SPI 1 at pins 11/12/13
+- SPI 2 at pins 0/4/1
+- SPI 3 at pins 11/12/13
+- SPI 4 at Pin MOSI/MISO/SCK This is the default SPI device at the MOSI/MISO/SCK labelled pins.
+
+or other combinations.
+
+
+SAMD21 PWM assignments
+``````````````````````
+
+The TCC/TC device numbers 0, 1 and 2 can be used for PWM. Device 0 has four
+channels, device 1 and 2 have two channels. So in total 3 different PWM
+frequencies can be used, and 8 different duty cycle values.
+
+The DAC output for the Adafruit ItsyBitsy M0 Express board is available at the pin A0.
+
+.. _samd51_pinout_table:
+
+Adafruit ItsyBitsy M4 Express pin assignment table
+--------------------------------------------------
+
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+Pin GPIO Pin name     IRQ  ADC  ADC  Serial Serial  TC    PWM   PWM
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+  2 PA02           A0   2    0    -     -      -     -     -     -
+  5 PA05           A1   5    5    -     -     0/1   0/1    -     -
+ 40 PB08           A2   8    2    0     -     4/0   4/0    -     -
+ 41 PB09           A3   9    3    1     -     4/1   4/1    -     -
+  4 PA04           A4   4    4    -     -     0/0   0/0    -     -
+  6 PA06           A5   6    6    -     -     0/2   1/0    -     -
+ 16 PA16           D0   0    -    -    1/0    3/1   2/0   1/0   0/4
+ 17 PA17           D1   1    -    -    1/1    3/0   2/1   1/1   0/5
+  7 PA07           D2   7    7    -     -     0/3   1/1    -     -
+ 54 PB22           D3  22    -    -    1/2    5/2   7/0    -     -
+ 14 PA14           D4  14    -    -    2/2    4/2   3/0   2/0   1/2
+ 15 PA15           D5  15    -    -    2/3    4/3   3/1   2/1   1/3
+ 18 PA18           D7   2    -    -    1/2    3/2   3/0   1/2   0/6
+ 19 PA19           D9   3    -    -    1/3    3/3   3/1   1/3   0/7
+ 20 PA20          D10   4    -    -    5/2    3/2   7/0   1/4   0/0
+ 21 PA21          D11   5    -    -    5/3    3/3   7/1   1/5   0/1
+ 23 PA23          D12   7    -    -    3/1    5/0   4/1   1/7   0/3
+ 22 PA22          D13   6    -    -    3/0    5/1   4/0   1/6   0/2
+ 34 PB02  DOTSTAR_CLK   2   14    -     -     5/0   6/0   2/2    -
+ 35 PB03 DOTSTAR_DATA   9   15    -     -     5/1   6/1    -     -
+ 43 PB11     FLASH_CS  12    -    -     -     4/3   5/1   0/5   1/1
+ 11 PA11   FLASH_HOLD  11   11    -    0/3    2/3   1/1   0/3   1/7
+  9 PA09   FLASH_MISO   9    9    3    0/1    2/0   0/1   0/1   1/5
+  8 PA08   FLASH_MOSI   -    8    2    0/0    2/1   0/0   0/0   1/4
+ 42 PB10    FLASH_SCK  10    -    -     -     4/2   5/0   0/4   1/0
+ 10 PA10     FLASH_WP  10   10    -    0/2    2/2   1/0   0/2   1/6
+ 55 PB23         MISO   7    -    -    1/3    5/3   7/1    -     -
+  0 PA00         MOSI   0    -    -     -     1/0   2/0    -     -
+  1 PA01          SCK   1    -    -     -     1/1   2/1    -     -
+ 13 PA13          SCL  13    -    -    2/1    4/0   2/1   0/7   1/3
+ 12 PA12          SDA  12    -    -    2/0    4/1   2/0   0/6   1/2
+ 30 PA30        SWCLK  14    -    -    7/2    1/2   6/0   2/0    -
+ 31 PA31        SWDIO  15    -    -    7/3    1/3   6/1   2/1    -
+ 24 PA24       USB_DM   8    -    -    3/2    5/2   5/0   2/2    -
+ 25 PA25       USB_DP   9    -    -    3/3    5/3   5/1    -     -
+  3 PA03            -   3   10    -     -      -     -     -     -
+ 27 PA27            -  11    -    -     -      -     -     -     -
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+
+
+Description of the columns:
+
+- *Pin* - The number that is expected at ``machine.Pin(n)``, if the pin is given
+  as a number. This is NOT the GPIO number, but the board pin number, as
+  given in the board specific definition file.
+- *GPIO* - The GPIO number.
+- *Pin Name* The name of a Pin which is expected argument to ``machine.Pin("name")``.
+- *IRQ* - The IRQ number assigned to that GPIO, used internally by ``Pin.irq()``. When
+  using ``Pin.irq()``, different pins must use different IRQs
+- *ADC* - The ADC0/1 channel assigned to the pin. When using ADC, different pins must
+  not use the same ADC device and channel.
+- *Serial* - Two columns with optional Serial signal assignments. Both may be used.
+  The cell content is device #/pad #. The pad # is the respective internal
+  signal of that serial device. Details below.
+- *TC* - These device are currently not assigned to Pin. the TC device pair 0/1
+  is used for ``ticks_us()``.
+- *PWM* - Two columns with assignments of the TCC modules for PWM
+  The cell content is device #/output #. Details below.
+
+SAMD51 UART assignments
+```````````````````````
+The UART devices and signals must be chosen according to the following rules:
+
+- The TX signal must be at a Pin with pad numbers 0, like Pin 1 with serial
+  device 3.
+- The RX pin may be assigned to one of the other pads.
+
+Examples for Adafruit ItsyBitsy 4 Express:
+
+- uart 0 at pins A4/A1
+- uart 1 at pins 1/0   This is the default UART at the RX/TX labelled pins
+- uart 2 at pins SCL/SDA  This is the default I2C device at the SDA/SCl labelled pin
+- uart 3 at pins 0/1
+- uart 4 at pins SDA/SCL
+- uart 5 at pins D12/D13
+
+or other combinations.
+
+SAMD51 I2C assignments
+``````````````````````
+The I2C devices and signals must be chosen according to the following rules:
+
+- The SDA signal must be at a Pin with pad numbers 0.
+- The SCL signal must be at a Pin with pad numbers 1.
+
+Examples for Adafruit ItsyBitsy M0 Express:
+
+- I2C 0 at pins A3/A4
+- I2C 1 at pins 0/1
+- I2C 2 at the pins SDA/SCL
+- I2C 3 at the pins 1/0
+- I2C 4 at the pins A2/A3
+- I2C 5 at the pins 12/13
+
+or other combinations.
+
+SAMD51 SPI assignments
+``````````````````````
+The SPI devices and signals must be chosen according to the following rules:
+
+- The following pad number pairs are suitable for MOSI/SCK: 0/1 and 3/1.
+- The MISO signal must be at a Pin with a different pad number than MOSI or SCK.
+
+Examples for Adafruit ItsyBitsy M0 Express:
+
+- SPI 1 at Pin MOSI/MISO/SCK  This is the default SPI device at the MOSI/MISO/SCK labelled pins.
+- SPI 3 at pins 13/11/12
+- SPI 5 at pins 12/3/13
+
+or other combinations.
+
+
+SAMD51 PWM assignments
+``````````````````````
+
+The TCC/PWM device numbers 0 through 4 can be used for PWM. Device 0 has six
+channels, device 1 has four channels, device 2 has three channels and devices
+3 and 4 have two channels. So in total up to 5 different PWM frequencies
+can be used, and up to 17 different duty cycle values. Note that these numbers
+do not apply to every board.
+
+The DAC outputs for the Adafruit ItsyBitsy M4 Express board are available at the pins A0 and A1.
+
+Adafruit Feather M4 Express pin assignment table
+------------------------------------------------
+
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+Pin GPIO Pin name     IRQ  ADC  ADC  Serial Serial  TC    PWM   PWM
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+  2 PA02           A0   2    0    -     -      -     -     -      -
+  5 PA05           A1   5    5    -     -     0/1   0/1    -      -
+ 40 PB08           A2   8    2    0     -     4/0   4/0    -      -
+ 41 PB09           A3   9    3    1     -     4/1   4/1    -      -
+  4 PA04           A4   4    4    -     -     0/0   0/0    -      -
+ 38 PB06           A5   6    -    8     -      -     -     -      -
+ 49 PB17           D0   1    -    -    5/1     -    6/1   3/1    0/5
+ 48 PB16           D1   0    -    -    5/0     -    6/0   3/0    0/4
+ 14 PA14           D4  14    -    -    2/2    4/2   3/0   2/0    1/2
+ 16 PA16           D5   0    -    -    1/0    3/1   2/0   1/0    0/4
+ 18 PA18           D6   2    -    -    1/2    3/2   3/0   1/2    0/6
+ 19 PA19           D9   3    -    -    1/3    3/3   3/1   1/3    0/7
+  3 PA03         AREF   3   10    -     -      -     -     -      -
+ 20 PA20          D10   4    -    -    5/2    3/2   7/0   1/4    0/0
+ 21 PA21          D11   5    -    -    5/3    3/3   7/1   1/5    0/1
+ 22 PA22          D12   6    -    -    3/0    5/1   4/0   1/6    0/2
+ 23 PA23          D13   7    -    -    3/1    5/0   4/1   1/7    0/3
+ 43 PB11     FLASH_CS  12    -    -     -     4/3   5/1   0/5    1/1
+ 11 PA11   FLASH_HOLD  11   11    -    0/3    2/3   1/1   0/3    1/7
+  9 PA09   FLASH_MISO   9    9    3    0/1    2/0   0/1   0/1    1/5
+  8 PA08   FLASH_MOSI   -    8    2    0/0    2/1   0/0   0/0    1/4
+ 42 PB10    FLASH_SCK  10    -    -     -     4/2   5/0   0/4    1/0
+ 10 PA10     FLASH_WP  10   10    -    0/2    2/2   1/0   0/2    1/6
+ 54 PB22         MISO  22    -    -    1/2    5/2   7/0    -      -
+ 55 PB23         MOSI   7    -    -    1/3    5/3   7/1    -      -
+ 35 PB03     NEOPIXEL   9   15    -     -     5/1   6/1    -      -
+ 17 PA17          SCK   1    -    -    1/1    3/0   2/1   1/1    0/5
+ 13 PA13          SCL  13    -    -    2/1    4/0   2/1   0/7    1/3
+ 12 PA12          SDA  12    -    -    2/0    4/1   2/0   0/6    1/2
+ 30 PA30        SWCLK  14    -    -    7/2    1/2   6/0   2/0     -
+ 31 PA31        SWDIO  15    -    -    7/3    1/3   6/1   2/1     -
+ 24 PA24       USB_DM   8    -    -    3/2    5/2   5/0   2/2     -
+ 25 PA25       USB_DP   9    -    -    3/3    5/3   5/1    -      -
+ 33 PB01         VDIV   1   13    -     -     5/3   7/1    -      -
+  0 PA00            -   0    -    -     -     1/0   2/0    -      -
+  1 PA01            -   1    -    -     -     1/1   2/1    -      -
+  6 PA06            -   6    6    -     -     0/2   1/0    -      -
+  7 PA07            -   7    7    -     -     0/3   1/1    -      -
+ 15 PA15            -  15    -    -    2/3    4/3   3/1   2/1    1/3
+ 27 PA27            -  11    -    -     -      -     -     -      -
+ 32 PB00            -   9   12    -     -     5/2   7/0    -      -
+ 34 PB02            -   2   14    -     -     5/0   6/0   2/2     -
+ 36 PB04            -   4    -    6     -      -     -     -      -
+ 37 PB05            -   5    -    7     -      -     -     -      -
+ 39 PB07            -   7    -    9     -      -     -     -      -
+ 44 PB12            -  12    -    -    4/0     -    4/0   3/0    0/0
+ 45 PB13            -  13    -    -    4/1     -    4/1   3/1    0/1
+ 46 PB14            -  14    -    -    4/2     -    5/0   4/0    0/2
+ 47 PB15            -  15    -    -    4/3     -    5/1   4/1    0/3
+ 62 PB30            -  14    -    -    7/0    5/1   0/0   4/0    0/6
+ 63 PB31            -  15    -    -    7/1    5/0   0/1   4/1    0/7
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+
+For the definition of the table columns see the explanation at the table for
+Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
+
+The default devices at the board are:
+
+- UART 5 at pins 0/1, labelled RX/TX
+- I2C 2 at pins 21/20, labelled SDA/SCL
+- SPI 1 at pins 22/23/24, labelled MOSI, MISO and SCK
+- DAC output on pins 14 and 15, labelled A0 and A1
+
+SEEED XIAO pin assignment table
+-------------------------------
+
+=== ==== ============ ==== ==== ====== ====== ====== ======
+Pin GPIO Pin name     IRQ  ADC  Serial Serial TCC/TC TCC/TC
+=== ==== ============ ==== ==== ====== ====== ====== ======
+  2 PA02        A0_D0   2    0     -      -     -      -
+  4 PA04        A1_D1   4    4     -     0/0   0/0     -
+ 10 PA10        A2_D2  10   18    0/2    2/2   1/0    0/2
+ 11 PA11        A3_D3  11   19    0/3    2/3   1/1    0/3
+  8 PA08        A4_D4   -   16    0/0    2/0   0/0    1/2
+  9 PA09        A5_D5   9   17    0/1    2/1   0/1    1/3
+ 40 PB08        A6_D6   8    2     -     4/0   4/0     -
+ 41 PB09        A7_D7   9    3     -     4/1   4/1     -
+  7 PA07        A8_D8   7    7     -     0/3   1/1     -
+  5 PA05        A9_D9   5    5     -     0/1   0/1     -
+  6 PA06      A10_D10   6    6     -     0/2   1/0     -
+ 18 PA18       RX_LED   2    -    1/2    3/2   3/0    0/2
+ 30 PA30        SWCLK  10    -     -     1/2   1/0     -
+ 31 PA31        SWDIO  11    -     -     1/3   1/1     -
+ 19 PA19       TX_LED   3    -    1/3    3/3   3/1    0/3
+ 24 PA24       USB_DM  12    -    3/2    5/2   5/0    1/2
+ 25 PA25       USB_DP  13    -    3/3    5/3   5/1    1/3
+ 17 PA17     USER_LED   1    -    1/1    3/1   2/1    0/7
+  0 PA00            -   0    -     -     1/0   2/0     -
+  1 PA01            -   1    -     -     1/1   2/1     -
+  3 PA03            -   3    1     -      -     -      -
+ 12 PA12            -  12    -    2/0    4/0   2/0    0/6
+ 13 PA13            -  13    -    2/1    4/1   2/0    0/7
+ 14 PA14            -  14    -    2/2    4/2   3/0    0/4
+ 15 PA15            -  15    -    2/3    4/3   3/1    0/5
+ 16 PA16            -   0    -    1/0    3/0   2/0    0/6
+ 20 PA20            -   4    -    5/2    3/2   7/0    0/4
+ 21 PA21            -   5    -    5/3    3/3   7/1    0/7
+ 22 PA22            -   6    -    3/0    5/0   4/0    0/4
+ 23 PA23            -   7    -    3/1    5/1   4/1    0/5
+ 27 PA27            -  15    -     -      -     -      -
+ 28 PA28            -   8    -     -      -     -      -
+ 34 PB02            -   2   10     -     5/0   6/0     -
+ 35 PB03            -   3   11     -     5/1   6/1     -
+ 42 PB10            -  10    -     -     4/2   5/0    0/4
+ 43 PB11            -  11    -     -     4/3   5/1    0/5
+ 54 PB22            -   6    -     -     5/2   7/0     -
+ 55 PB23            -   7    -     -     5/3   7/1     -
+=== ==== ============ ==== ==== ====== ====== ====== ======
+
+For the definition of the table columns see the explanation at the table for
+Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
+
+The default devices at the board are:
+
+- UART 4 at pins 7/6, labelled A6_D6/A7_D7
+- I2C 2 at pins 4/5, labelled A4_D4/A5_D5
+- SPI 0 at pins 10/9/8, labelled A10_D10, A9_D9 and A8_D8
+- DAC output on pin 0, labelled A0_D0
+
+Adafruit Feather M0 Express pin assignment table
+------------------------------------------------
+
+=== ==== ============ ==== ==== ====== ====== ====== ======
+Pin GPIO Pin name     IRQ  ADC  Serial Serial TCC/TC TCC/TC
+=== ==== ============ ==== ==== ====== ====== ====== ======
+  2 PA02           A0   2    0     -      -     -      -
+ 40 PB08           A1   8    2     -     4/0   4/0     -
+ 41 PB09           A2   9    3     -     4/1   4/1     -
+  4 PA04           A3   4    4     -     0/0   0/0     -
+  5 PA05           A4   5    5     -     0/1   0/1     -
+ 34 PB02           A5   2   10     -     5/0   6/0     -
+ 11 PA11           D0  11   19    0/3    2/3   1/1    0/3
+ 10 PA10           D1  10   18    0/2    2/2   1/0    0/2
+ 14 PA14           D2  14    -    2/2    4/2   3/0    0/4
+  9 PA09           D3   9   17    0/1    2/1   0/1    1/3
+  8 PA08           D4   -   16    0/0    2/0   0/0    1/2
+ 15 PA15           D5  15    -    2/3    4/3   3/1    0/5
+ 20 PA20           D6   4    -    5/2    3/2   7/0    0/4
+ 21 PA21           D7   5    -    5/3    3/3   7/1    0/7
+  7 PA07           D9   7    7     -     0/3   1/1     -
+ 55 PB23           RX   7    -     -     5/3   7/1     -
+ 54 PB22           TX   6    -     -     5/2   7/0     -
+ 18 PA18          D10   2    -    1/2    3/2   3/0    0/2
+ 16 PA16          D11   0    -    1/0    3/0   2/0    0/6
+ 19 PA19          D12   3    -    1/3    3/3   3/1    0/3
+ 17 PA17          D13   1    -    1/1    3/1   2/1    0/7
+ 13 PA13     FLASH_CS  13    -    2/1    4/1   2/0    0/7
+ 35 PB03       LED_RX   3   11     -     5/1   6/1     -
+ 27 PA27       LED_TX  15    -     -      -     -      -
+ 12 PA12         MISO  12    -    2/0    4/0   2/0    0/6
+ 42 PB10         MOSI  10    -     -     4/2   5/0    0/4
+  6 PA06     NEOPIXEL   6    6     -     0/2   1/0     -
+ 43 PB11          SCK  11    -     -     4/3   5/1    0/5
+ 23 PA23          SCL   7    -    3/1    5/1   4/1    0/5
+ 22 PA22          SDA   6    -    3/0    5/0   4/0    0/4
+ 30 PA30        SWCLK  10    -     -     1/2   1/0     -
+ 31 PA31        SWDIO  11    -     -     1/3   1/1     -
+ 24 PA24       USB_DM  12    -    3/2    5/2   5/0    1/2
+ 25 PA25       USB_DP  13    -    3/3    5/3   5/1    1/3
+  0 PA00            -   0    -     -     1/0   2/0     -
+  1 PA01            -   1    -     -     1/1   2/1     -
+  3 PA03            -   3    1     -      -     -      -
+ 28 PA28            -   8    -     -      -     -      -
+=== ==== ============ ==== ==== ====== ====== ====== ======
+
+For the definition of the table columns see the explanation at the table for
+Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
+
+The default devices at the board are:
+
+- UART 5 at pins 21/20, labelled RX/TX
+- I2C 3 at pins 22/23, labelled SDA/SCL
+- SPI 4 at pins 24/25/26, labelled MOSI, MISO and SCK
+- DAC output on pin 14, labelled A0
+
+Adafruit Trinket M0 pin assignment table
+------------------------------------------------
+
+=== ==== ============ ==== ==== ====== ====== ====== ======
+Pin GPIO Pin name     IRQ  ADC  Serial Serial TCC/TC TCC/TC
+=== ==== ============ ==== ==== ====== ====== ====== ======
+  8 PA08           D0   -   16    0/0    2/0   0/0    1/2
+  2 PA02           D1   2    0     -      -     -      -
+  9 PA09           D2   9   17    0/1    2/1   0/1    1/3
+  7 PA07           D3   7    7     -     0/3   1/1     -
+  6 PA06           D4   6    6     -     0/2   1/0     -
+  1 PA01  DOTSTAR_CLK   1    -     -     1/1   2/1     -
+  0 PA00 DOTSTAR_DATA   0    -     -     1/0   2/0     -
+ 10 PA10          LED  10   18    0/2    2/2   1/0    0/2
+ 30 PA30        SWCLK  10    -     -     1/2   1/0     -
+ 31 PA31        SWDIO  11    -     -     1/3   1/1     -
+ 24 PA24       USB_DM  12    -    3/2    5/2   5/0    1/2
+ 25 PA25       USB_DP  13    -    3/3    5/3   5/1    1/3
+  3 PA03            -   3    1     -      -     -      -
+  4 PA04            -   4    4     -     0/0   0/0     -
+  5 PA05            -   5    5     -     0/1   0/1     -
+ 11 PA11            -  11   19    0/3    2/3   1/1    0/3
+ 14 PA14            -  14    -    2/2    4/2   3/0    0/4
+ 15 PA15            -  15    -    2/3    4/3   3/1    0/5
+ 16 PA16            -   0    -    1/0    3/0   2/0    0/6
+ 17 PA17            -   1    -    1/1    3/1   2/1    0/7
+ 18 PA18            -   2    -    1/2    3/2   3/0    0/2
+ 19 PA19            -   3    -    1/3    3/3   3/1    0/3
+ 22 PA22            -   6    -    3/0    5/0   4/0    0/4
+ 23 PA23            -   7    -    3/1    5/1   4/1    0/5
+ 27 PA27            -  15    -     -      -     -      -
+ 28 PA28            -   8    -     -      -     -      -
+=== ==== ============ ==== ==== ====== ====== ====== ======
+
+For the definition of the table columns see the explanation at the table for
+Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
+
+The default devices at the board are:
+
+- UART 0 at pins 3/4, labelled D3/D4
+- I2C 2 at pins 0/2, labelled D0/D2
+- SPI 0 at pins 4/2/3, labelled D4, D2 and D0
+- DAC output on pin 1, labelled D1
+
+SAMD21 Xplained PRO pin assignment table
+----------------------------------------
+
+=== ==== ============ ==== ==== ====== ====== ====== ======
+Pin GPIO Pin name     IRQ  ADC  Serial Serial TCC/TC TCC/TC
+=== ==== ============ ==== ==== ====== ====== ====== ======
+ 32 PB00    EXT1_PIN3   0    8     -     5/2   7/0     -
+ 33 PB01    EXT1_PIN4   1    9     -     5/3   7/1     -
+ 38 PB06    EXT1_PIN5   6   14     -      -     -      -
+ 39 PB07    EXT1_PIN6   7   15     -      -     -      -
+ 34 PB02    EXT1_PIN7   2   10     -     5/0   6/0     -
+ 35 PB03    EXT1_PIN8   3   11     -     5/1   6/1     -
+ 36 PB04    EXT1_PIN9   4   12     -      -     -      -
+ 37 PB05   EXT1_PIN10   5   13     -      -     -      -
+  8 PA08   EXT1_PIN11   -   16    0/0    2/0   0/0    1/2
+  9 PA09   EXT1_PIN12   9   17    0/1    2/1   0/1    1/3
+ 41 PB09   EXT1_PIN13   9    3     -     4/1   4/1     -
+ 40 PB08   EXT1_PIN14   8    2     -     4/0   4/0     -
+  5 PA05   EXT1_PIN15   5    5     -     0/1   0/1     -
+  6 PA06   EXT1_PIN16   6    6     -     0/2   1/0     -
+  4 PA04   EXT1_PIN17   4    4     -     0/0   0/0     -
+  7 PA07   EXT1_PIN18   7    7     -     0/3   1/1     -
+ 10 PA10    EXT2_PIN3  10   18    0/2    2/2   1/0    0/2
+ 11 PA11    EXT2_PIN4  11   19    0/3    2/3   1/1    0/3
+ 20 PA20    EXT2_PIN5   4    -    5/2    3/2   7/0    0/4
+ 21 PA21    EXT2_PIN6   5    -    5/3    3/3   7/1    0/7
+ 44 PB12    EXT2_PIN7  12    -    4/0     -    4/0    0/6
+ 45 PB13    EXT2_PIN8  13    -    4/1     -    4/1    0/7
+ 46 PB14    EXT2_PIN9  14    -    4/2     -    5/0     -
+ 47 PB15   EXT2_PIN10  15    -    4/3     -    5/1     -
+ 43 PB11   EXT2_PIN13  11    -     -     4/3   5/1    0/5
+ 42 PB10   EXT2_PIN14  10    -     -     4/2   5/0    0/4
+ 17 PA17   EXT2_PIN15   1    -    1/1    3/1   2/1    0/7
+ 18 PA18   EXT2_PIN16   2    -    1/2    3/2   3/0    0/2
+ 16 PA16   EXT2_PIN17   0    -    1/0    3/0   2/0    0/6
+ 19 PA19   EXT2_PIN18   3    -    1/3    3/3   3/1    0/3
+  2 PA02    EXT3_PIN3   2    0     -      -     -      -
+  3 PA03    EXT3_PIN4   3    1     -      -     -      -
+ 15 PA15    EXT3_PIN6  15    -    2/3    4/3   3/1    0/5
+ 12 PA12    EXT3_PIN7  12    -    2/0    4/0   2/0    0/6
+ 13 PA13    EXT3_PIN8  13    -    2/1    4/1   2/0    0/7
+ 28 PA28    EXT3_PIN9   8    -     -      -     -      -
+ 27 PA27   EXT3_PIN10  15    -     -      -     -      -
+ 49 PB17   EXT3_PIN15   1    -    5/1     -    6/1    0/5
+ 54 PB22   EXT3_PIN16   6    -     -     5/2   7/0     -
+ 48 PB16   EXT3_PIN17   9    -    5/0     -    6/0    0/4
+ 55 PB23   EXT3_PIN18   7    -     -     5/3   7/1     -
+ 62 PB30          LED  14    -     -     5/0   0/0    1/2
+ 30 PA30        SWCLK  10    -     -     1/2   1/0     -
+ 31 PA31        SWDIO  11    -     -     1/3   1/1     -
+ 24 PA24       USB_DM  12    -    3/2    5/2   5/0    1/2
+ 25 PA25       USB_DP  13    -    3/3    5/3   5/1    1/3
+  0 PA00            -   0    -     -     1/0   2/0     -
+  1 PA01            -   1    -     -     1/1   2/1     -
+ 14 PA14            -  14    -    2/2    4/2   3/0    0/4
+ 22 PA22            -   6    -    3/0    5/0   4/0    0/4
+ 23 PA23            -   7    -    3/1    5/1   4/1    0/5
+ 63 PB31            -  15    -     -     5/1   0/1    1/3
+=== ==== ============ ==== ==== ====== ====== ====== ======
+
+For the definition of the table columns see the explanation at the table for
+Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
+
+There are no pins labelled for default devices on this board. DAC output
+is on pin 32, labelled EXT3_PIN3
+
+Minisam M4 pin assignment table
+-------------------------------
+
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+Pin GPIO Pin name     IRQ  ADC  ADC  Serial Serial  TC    PWM   PWM
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+ 16 PA16           D0   0    -    -    1/0    3/1   2/0   1/0   0/4
+ 17 PA17           D1   1    -    -    1/1    3/0   2/1   1/1   0/5
+ 19 PA19           D3   3    -    -    1/3    3/3   3/1   1/3   0/7
+ 20 PA20           D4   4    -    -    5/2    3/2   7/0   1/4   0/0
+ 21 PA21           D5   5    -    -    5/3    3/3   7/1   1/5   0/1
+  2 PA02        A0_D9   2    0    -     -      -     -     -     -
+ 40 PB08       A1_D10   8    2    0     -     4/0   4/0    -     -
+ 41 PB09       A2_D11   9    3    1     -     4/1   4/1    -     -
+  4 PA04       A3_D12   4    4    -     -     0/0   0/0    -     -
+  5 PA05       A4_D13   5    5    -     -     0/1   0/1    -     -
+  6 PA06           A5   6    6    -     -     0/2   1/0    -     -
+  7 PA07        A6_D2   7    7    -     -     0/3   1/1    -     -
+  3 PA03         AREF   3   10    -     -      -     -     -     -
+  0 PA00       BUTTON   0    -    -     -     1/0   2/0    -     -
+ 34 PB02  DOTSTAR_CLK   2   14    -     -     5/0   6/0   2/2    -
+ 35 PB03 DOTSTAR_DATA   9   15    -     -     5/1   6/1    -     -
+ 15 PA15          LED  15    -    -    2/3    4/3   3/1   2/1   1/3
+ 55 PB23         MISO   7    -    -    1/3    5/3   7/1    -     -
+ 54 PB22         MOSI  22    -    -    1/2    5/2   7/0    -     -
+  1 PA01          SCK   1    -    -     -     1/1   2/1    -     -
+ 13 PA13          SCL  13    -    -    2/1    4/0   2/1   0/7   1/3
+ 12 PA12          SDA  12    -    -    2/0    4/1   2/0   0/6   1/2
+ 30 PA30        SWCLK  14    -    -    7/2    1/2   6/0   2/0    -
+ 31 PA31        SWDIO  15    -    -    7/3    1/3   6/1   2/1    -
+ 24 PA24       USB_DM   8    -    -    3/2    5/2   5/0   2/2    -
+ 25 PA25       USB_DP   9    -    -    3/3    5/3   5/1    -     -
+  8 PA08            -   -    8    2    0/0    2/1   0/0   0/0   1/4
+  9 PA09            -   9    9    3    0/1    2/0   0/1   0/1   1/5
+ 10 PA10            -  10   10    -    0/2    2/2   1/0   0/2   1/6
+ 11 PA11            -  11   11    -    0/3    2/3   1/1   0/3   1/7
+ 14 PA14            -  14    -    -    2/2    4/2   3/0   2/0   1/2
+ 18 PA18            -   2    -    -    1/2    3/2   3/0   1/2   0/6
+ 22 PA22            -   6    -    -    3/0    5/1   4/0   1/6   0/2
+ 23 PA23            -   7    -    -    3/1    5/0   4/1   1/7   0/3
+ 27 PA27            -  11    -    -     -      -     -     -     -
+ 42 PB10            -  10    -    -     -     4/2   5/0   0/4   1/0
+ 43 PB11            -  12    -    -     -     4/3   5/1   0/5   1/1
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+
+For the definition of the table columns see the explanation at the table for
+Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
+
+The default devices at the board are:
+
+- UART 1 at pins 6/7, labelled D0/D1
+- I2C 2 at pins 14/15, labelled SDA/SCL
+- SPI 1 at pins 16/17/18, labelled MOSI, MISO and SCK
+- DAC output on pins 0 and 4, labelled A0_D9 and A4_D13
+
+Seeed WIO Terminal pin assignment table
+---------------------------------------
+
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+Pin GPIO Pin name     IRQ  ADC  ADC  Serial Serial  TC    PWM   PWM
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+ 33 PB01           CS   1   13    -     -    5/3    7/1    -     -
+ 59 PB27           RX  13    -    -    2/1   4/0     -    1/3    -
+ 58 PB26           TX  12    -    -    2/0   4/1     -    1/2    -
+ 79 PC15   3V3_ENABLE  15    -    -    7/3   6/3     -    0/5   1/1
+ 78 PC14    5V_ENABLE  14    -    -    7/2   6/2     -    0/4   1/0
+ 40 PB08        A0_D0   8    2    0     -    4/0    4/0    -     -
+ 41 PB09        A1_D1   9    3    1     -    4/1    4/1    -     -
+  7 PA07        A2_D2   7    7    -     -    0/3    1/1    -     -
+ 36 PB04        A3_D3   4    -    6     -     -      -     -     -
+ 37 PB05        A4_D4   5    -    7     -     -      -     -     -
+ 38 PB06        A5_D5   6    -    8     -     -      -     -     -
+  4 PA04        A6_D6   4    4    -     -    0/0    0/0    -     -
+ 39 PB07        A7_D7   7    -    9     -     -      -     -     -
+  6 PA06        A8_D8   6    6    -     -    0/2    1/0    -     -
+ 90 PC26     BUTTON_1  10    -    -     -     -      -     -     -
+ 91 PC27     BUTTON_2  11    -    -    1/0    -      -     -     -
+ 92 PC28     BUTTON_3  12    -    -    1/1    -      -     -     -
+107 PD11       BUZZER   6    -    -    7/3   6/3     -    0/4    -
+ 47 PB15       GPCLK0  15    -    -    4/3    -     5/1   4/1   0/3
+ 44 PB12       GPCLK1  12    -    -    4/0    -     4/0   3/0   0/0
+ 45 PB13       GPCLK2  13    -    -    4/1    -     4/1   3/1   0/1
+ 48 PB16     I2C_BCLK   0    -    -    5/0    -     6/0   3/0   0/4
+ 20 PA20    I2S_LRCLK   4    -    -    5/2   3/2    7/0   1/4   0/0
+ 21 PA21     I2S_SDIN   5    -    -    5/3   3/3    7/1   1/5   0/1
+ 22 PA22    I2S_SDOUT   6    -    -    3/0   5/1    4/0   1/6   0/2
+ 50 PB18     LCD_MISO   2    -    -    5/2   7/2     -    1/0    -
+ 51 PB19     LCD_MOSI   3    -    -    5/3   7/3     -    1/1    -
+ 52 PB20      LCD_SCK   4    -    -    3/0   7/1     -    1/2    -
+ 53 PB21       LCD_CS   5    -    -    3/1   7/0     -    1/3    -
+ 70 PC06      LCD_D/C   6    -    -    6/2    -      -     -     -
+ 71 PC07    LCD_RESET   9    -    -    6/3    -      -     -     -
+ 74 PC10       LCD_XL  10    -    -    6/2   7/2     -    0/0   1/4
+ 76 PC12       LCD_XR  12    -    -    7/0   6/1     -    0/2   1/6
+ 77 PC13       LCD_YD  13    -    -    7/1   6/0     -    0/3   1/7
+ 75 PC11       LCD_YU  11    -    -    6/3   7/3     -    0/1   1/5
+ 15 PA15     LED_BLUE  15    -    -    2/3   4/3    3/1   2/1   1/3
+ 69 PC05      LED_LCD   5    -    -    6/1    -      -     -     -
+ 94 PC30          MIC  14    -   12     -     -      -     -     -
+ 32 PB00         MISO   9   12    -     -    5/2    7/0    -     -
+ 34 PB02         MOSI   2   14    -     -    5/0    6/0   2/2    -
+ 35 PB03          SCK   9   15    -     -    5/1    6/1    -     -
+ 12 PA12         SCL0  12    -    -    2/0   4/1    2/0   0/6   1/2
+ 13 PA13         SDA0  13    -    -    2/1   4/0    2/1   0/7   1/3
+ 16 PA16         SCL1   0    -    -    1/0   3/1    2/0   1/0   0/4
+ 17 PA17         SDA1   1    -    -    1/1   3/0    2/1   1/1   0/5
+117 PD21       SD_DET  11    -    -    1/3   3/3     -    1/1    -
+ 83 PC19        SD_CS   3    -    -    6/3   0/3     -    0/3    -
+ 82 PC18      SD_MISO   2    -    -    6/2   0/2     -    0/2    -
+ 80 PC16      SD_MOSI   0    -    -    6/0   0/1     -    0/0    -
+ 81 PC17       SD_SCK   1    -    -    6/1   0/0     -    0/1    -
+ 30 PA30        SWCLK  14    -    -    7/2   1/2    6/0   2/0    -
+ 31 PA31        SWDIO  15    -    -    7/3   1/3    6/1   2/1    -
+108 PD12     SWITCH_B   7    -    -     -     -      -    0/5    -
+116 PD20     SWITCH_U  10    -    -    1/2   3/2     -    1/0    -
+104 PD08     SWITCH_X   3    -    -    7/0   6/1     -    0/1    -
+105 PD09     SWITCH_Y   4    -    -    7/1   6/0     -    0/2    -
+106 PD10     SWITCH_Z   5    -    -    7/2   6/2     -    0/3    -
+ 24 PA24       USB_DM   8    -    -    3/2   5/2    5/0   2/2    -
+ 25 PA25       USB_DP   9    -    -    3/3   5/3    5/1    -     -
+  0 PA00            -   0    -    -     -    1/0    2/0    -     -
+  1 PA01            -   1    -    -     -    1/1    2/1    -     -
+  2 PA02            -   2    0    -     -     -      -     -     -
+  3 PA03            -   3   10    -     -     -      -     -     -
+  5 PA05            -   5    5    -     -    0/1    0/1    -     -
+  8 PA08            -   -    8    2    0/0   2/1    0/0   0/0   1/4
+  9 PA09            -   9    9    3    0/1   2/0    0/1   0/1   1/5
+ 10 PA10            -  10   10    -    0/2   2/2    1/0   0/2   1/6
+ 11 PA11            -  11   11    -    0/3   2/3    1/1   0/3   1/7
+ 14 PA14            -  14    -    -    2/2   4/2    3/0   2/0   1/2
+ 18 PA18            -   2    -    -    1/2   3/2    3/0   1/2   0/6
+ 19 PA19            -   3    -    -    1/3   3/3    3/1   1/3   0/7
+ 23 PA23            -   7    -    -    3/1   5/0    4/1   1/7   0/3
+ 27 PA27            -  11    -    -     -     -      -     -     -
+ 42 PB10            -  10    -    -     -    4/2    5/0   0/4   1/0
+ 43 PB11            -  12    -    -     -    4/3    5/1   0/5   1/1
+ 46 PB14            -  14    -    -    4/2    -     5/0   4/0   0/2
+ 49 PB17            -   1    -    -    5/1    -     6/1   3/1   0/5
+ 54 PB22            -  22    -    -    1/2   5/2    7/0    -     -
+ 55 PB23            -   7    -    -    1/3   5/3    7/1    -     -
+ 56 PB24            -   8    -    -    0/0   2/1     -     -     -
+ 57 PB25            -   9    -    -    0/1   2/0     -     -     -
+ 60 PB28            -  14    -    -    2/2   4/2     -    1/4    -
+ 61 PB29            -  15    -    -    2/3   4/3     -    1/5    -
+ 62 PB30            -  14    -    -    7/0   5/1    0/0   4/0   0/6
+ 63 PB31            -  15    -    -    7/1   5/0    0/1   4/1   0/7
+ 64 PC00            -   0    -   10     -     -      -     -     -
+ 65 PC01            -   1    -   11     -     -      -     -     -
+ 66 PC02            -   2    -    4     -     -      -     -     -
+ 67 PC03            -   3    -    5     -     -      -     -     -
+ 68 PC04            -   4    -    -    6/0    -      -    0/0    -
+ 84 PC20            -   4    -    -     -     -      -    0/4    -
+ 85 PC21            -   5    -    -     -     -      -    0/5    -
+ 86 PC22            -   6    -    -    1/0   3/1     -    0/5    -
+ 87 PC23            -   7    -    -    1/1   3/0     -    0/7    -
+ 88 PC24            -   8    -    -    0/2   2/2     -     -     -
+ 89 PC25            -   9    -    -    0/3   2/3     -     -     -
+ 95 PC31            -  15    -   13     -     -      -     -     -
+ 96 PD00            -   0    -   14     -     -      -     -     -
+ 97 PD01            -   1    -   15     -     -      -     -     -
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+
+For the definition of the table columns see the explanation at the table for
+Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
+
+There seems to be no default pin assignment for this board.
+
+Sparkfun SAMD51 Thing Plus pin assignment table
+------------------------------------------------
+
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+Pin GPIO Pin name     IRQ  ADC  ADC  Serial Serial  TC    PWM   PWM
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+  2 PA02           A0   2    0    -     -      -     -     -     -
+ 40 PB08           A1   8    2    0     -     4/0   4/0    -     -
+ 41 PB09           A2   9    3    1     -     4/1   4/1    -     -
+  4 PA04           A3   4    4    -     -     0/0   0/0    -     -
+  5 PA05           A4   5    5    -     -     0/1   0/1    -     -
+ 34 PB02           A5   2   14    -     -     5/0   6/0   2/2    -
+ 13 PA13           D0  13    -    -    2/1    4/0   2/1   0/7   1/3
+ 12 PA12           D1  12    -    -    2/0    4/1   2/0   0/6   1/2
+  6 PA06           D4   6    6    -     -     0/2   1/0    -     -
+ 15 PA15           D5  15    -    -    2/3    4/3   3/1   2/1   1/3
+ 20 PA20           D6   4    -    -    5/2    3/2   7/0   1/4   0/0
+ 21 PA21           D7   5    -    -    5/3    3/3   7/1   1/5   0/1
+  7 PA07           D9   7    7    -     -     0/3   1/1    -     -
+ 18 PA18          D10   2    -    -    1/2    3/2   3/0   1/2   0/6
+ 16 PA16          D11   0    -    -    1/0    3/1   2/0   1/0   0/4
+ 19 PA19          D12   3    -    -    1/3    3/3   3/1   1/3   0/7
+ 17 PA17          D13   1    -    -    1/1    3/0   2/1   1/1   0/5
+ 10 PA10     FLASH_CS  10   10    -    0/2    2/2   1/0   0/2   1/6
+ 11 PA11   FLASH_MISO  11   11    -    0/3    2/3   1/1   0/3   1/7
+  8 PA08   FLASH_MOSI   -    8    2    0/0    2/1   0/0   0/0   1/4
+  9 PA09    FLASH_SCK   9    9    3    0/1    2/0   0/1   0/1   1/5
+ 43 PB11         MISO  12    -    -     -     4/3   5/1   0/5   1/1
+ 44 PB12         MOSI  12    -    -    4/0     -    4/0   3/0   0/0
+ 55 PB23          RXD   7    -    -    1/3    5/3   7/1    -     -
+ 35 PB03        RXLED   9   15    -     -     5/1   6/1    -     -
+ 45 PB13          SCK  13    -    -    4/1     -    4/1   3/1   0/1
+ 23 PA23          SCL   7    -    -    3/1    5/0   4/1   1/7   0/3
+ 22 PA22          SDA   6    -    -    3/0    5/1   4/0   1/6   0/2
+ 30 PA30        SWCLK  14    -    -    7/2    1/2   6/0   2/0    -
+ 31 PA31        SWDIO  15    -    -    7/3    1/3   6/1   2/1    -
+ 54 PB22          TXD  22    -    -    1/2    5/2   7/0    -     -
+ 27 PA27        TXLED  11    -    -     -      -     -     -     -
+ 24 PA24       USB_DM   8    -    -    3/2    5/2   5/0   2/2    -
+ 25 PA25       USB_DP   9    -    -    3/3    5/3   5/1    -     -
+  0 PA00            -   0    -    -     -     1/0   2/0    -     -
+  1 PA01            -   1    -    -     -     1/1   2/1    -     -
+  3 PA03            -   3   10    -     -      -     -     -     -
+ 14 PA14            -  14    -    -    2/2    4/2   3/0   2/0   1/2
+ 32 PB00            -   9   12    -     -     5/2   7/0    -     -
+ 33 PB01            -   1   13    -     -     5/3   7/1    -     -
+ 36 PB04            -   4    -    6     -      -     -     -     -
+ 37 PB05            -   5    -    7     -      -     -     -     -
+ 38 PB06            -   6    -    8     -      -     -     -     -
+ 39 PB07            -   7    -    9     -      -     -     -     -
+ 42 PB10            -  10    -    -     -     4/2   5/0   0/4   1/0
+ 46 PB14            -  14    -    -    4/2     -    5/0   4/0   0/2
+ 47 PB15            -  15    -    -    4/3     -    5/1   4/1   0/3
+ 48 PB16            -   0    -    -    5/0     -    6/0   3/0   0/4
+ 49 PB17            -   1    -    -    5/1     -    6/1   3/1   0/5
+ 62 PB30            -  14    -    -    7/0    5/1   0/0   4/0   0/6
+ 63 PB31            -  15    -    -    7/1    5/0   0/1   4/1   0/7
+=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
+
+For the definition of the table columns see the explanation at the table for
+Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
+
+The default devices at the board are:
+
+- UART 1 at pins 2/3, labelled RXD/TXD
+- I2C 5 at pins 20/21, labelled SDA/SCL
+- SPI 4 at pins 22/23/24, labelled MOSI, MISO and SCK
+- DAC output on pins 14 and 18, labelled A0 and A4
+
+Scripts for creating the pin assignment tables
+----------------------------------------------
+
+The tables shown above were created with small a Python script running on the target board::
+
+  from samd import pininfo
+  from machine import Pin
+  import os
+
+  def print_entry(e, txt):
+      print(txt, end=": ")
+      if e == 255:
+          print(" - ", end="")
+      else:
+          print("%d/%d" % (e >> 4, e & 0x0f), end="")
+
+  def print_pininfo(pin, info):
+      print("%3d" % pin, end=" ")
+      print("P%c%02d" % ("ABCD"[pin // 32], pin % 32), end="")
+      print(" %12s" % info[0], end="")
+      print(" IRQ:%2s" % (info[1] if info[1] != 255 else "-"), end="")
+      print(" ADC0:%2s" % (info[2] if info[2] != 255 else "-"), end="")
+      if len(info) == 7:
+          print_entry(info[3], " Serial1")
+          print_entry(info[4], " Serial2")
+          print_entry(info[5], " PWM1" if (info[5] >> 4) < 3 else "   TC")
+          print_entry(info[6], " PWM2")
+      else:
+          print(" ADC1:%2s" % (info[3] if info[3] != 255 else "-"), end="")
+          print_entry(info[4], " Serial1")
+          print_entry(info[5], " Serial2")
+          print_entry(info[6], " TC")
+          print_entry(info[7], " PWM1")
+          print_entry(info[8], " PWM2")
+      print()
+
+  def tblkey(i):
+      name = i[1][0]
+      if name != "-":
+          if len(name) < 3:
+              return " " + name
+          else:
+              return name
+      else:
+          return "zzzzzzz%03d" % i[0]
+
+  def table(num = 127):
+      pintbl = []
+      for i in range(num):
+          try:
+              pintbl.append((i, pininfo(i)))
+          except:
+              pass
+              # print("not defined")
+
+      pintbl.sort(key=tblkey)
+      for item in pintbl:
+          print_pininfo(item[0], item[1])
+
+  table()
diff --git a/docs/samd/quickref.rst b/docs/samd/quickref.rst
new file mode 100644
index 000000000..5e8298d1b
--- /dev/null
+++ b/docs/samd/quickref.rst
@@ -0,0 +1,469 @@
+.. _samd_quickref:
+
+Quick reference for the SAMD21/SAMD51 family
+============================================
+
+.. image:: img/itsybitsy_m4_express.jpg
+    :alt: Adafruit ItsyBitsy M4 Express board
+    :width: 640px
+
+The Adafruit ItsyBitsy M4 Express board.
+
+Below is a quick reference for SAMD21/SAMD51-based boards.  If it is your first time
+working with this board it may be useful to get an overview of the microcontroller:
+
+.. toctree::
+   :maxdepth: 1
+
+   general.rst
+   tutorial/intro.rst
+   pinout.rst
+
+
+Installing MicroPython
+----------------------
+
+See the corresponding section of tutorial: :ref:`samd_intro`. It also includes
+a troubleshooting subsection.
+
+General board control
+---------------------
+
+The MicroPython REPL is on the USB port, configured in VCP mode.
+Tab-completion is useful to find out what methods an object has.
+Paste mode (Ctrl-E) is useful to paste a large slab of Python code into
+the REPL.
+
+The :mod:`machine` module::
+
+    import machine
+
+    machine.freq()            # get the current frequency of the CPU
+    machine.freq(96_000_000)  # set the CPU frequency to 96 MHz
+
+The range accepted by the function call is 1_000_000 to 200_000_000 (1 MHz to 200 MHz)
+for SAMD51 and 1_000_000 to 48_000_000 (1 MHz to 48 MHz) for SAMD21. The safe
+range for SAMD51 according to the data sheet is 96 MHz to 120 MHz.
+At frequencies below 8 MHz USB will be disabled. Changing the frequency below 48 MHz
+impacts the baud rates of UART, I2C and SPI. These have to be set again after
+changing the CPU frequency. The ms and µs timers are not affected by the frequency
+change.
+
+
+Delay and timing
+----------------
+
+Use the :mod:`time <time>` module::
+
+    import time
+
+    time.sleep(1)           # sleep for 1 second
+    time.sleep_ms(500)      # sleep for 500 milliseconds
+    time.sleep_us(10)       # sleep for 10 microseconds
+    start = time.ticks_ms() # get millisecond counter
+    delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference
+
+
+Clock and time
+--------------
+
+Two groups of functions are provided for time information. All boards have the
+datetime(), mktime() and time() functions. Boards with a 32kHz crystal also
+provide an RTC() module. The epoch start date is 1.1.2000.
+
+Use the :mod:`time <time>` module::
+
+    import time
+
+    date_time = time.localtime()        # Show the actual date/time information
+    date_time = time.localtime(seconds) # decode the date/time form the seconds value
+    seconds = time.mktime(date_time_tuple) # Convert seconds to a datetime tuple
+    second = time.time()                # Return the actual system time.
+
+The format of the date_time tuple follows the standard. The µs value of the date_time
+tuple is ignored. On boards without the RTC module, time.localtime(seconds) sets the
+system time. Use of the Use the :mod:`RTC <RTC>` module::
+
+    from machine import RTC
+    rtc = RTC()
+    date_time = rtc.datetime()      # return the actual date & time.
+    rtc.datetime(date_time_tuple)   # Set date & time, ignoring weekday
+    date_time = rtc.now()           # Return date & time in Unix order.
+    rtc.calibration(value)          # Set a calibration factor
+
+The weekday value set will be ignored and calculated in the returned tuple from the
+actual date. rtc.now() is only provided at SAMD51 boards. The value used in the
+rtc.calibration() call has a range from -127 - 127. It defines roughly a
+ppm quantity, by which the clock can run faster or slower.
+
+
+Timers
+------
+
+The SAMD21/SAMD51 uses software timers. Use the :ref:`machine.Timer <machine.Timer>` class::
+
+    from machine import Timer
+
+    tim0 = Timer()
+    tim0.init(period=5000, mode=Timer.ONE_SHOT, callback=lambda t:print(0))
+
+    tim1 = Timer()
+    tim1.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(1))
+
+The period is in milliseconds.
+
+.. _samd_Pins_and_GPIO:
+
+Pins and GPIO
+-------------
+
+Use the :ref:`machine.Pin <machine.Pin>` class::
+
+    from machine import Pin
+
+    p0 = Pin('D0', Pin.OUT) # create output pin on GPIO0
+    p0.on()                 # set pin to "on" (high) level
+    p0.off()                # set pin to "off" (low) level
+    p0.value(1)             # set pin to on/high
+
+    p2 = Pin('D2', Pin.IN)  # create input pin on GPIO2
+    print(p2.value())       # get value, 0 or 1
+
+    p4 = Pin('D4', Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor
+    p7 = Pin("PA07", Pin.OUT, value=1) # set pin high on creation
+
+Pins can be denoted by a string or a number. The string is either the
+pin label of the respective board, like "D0" or "SDA", or in the form
+"Pxnn", where x is A,B,C or D, and nn a two digit number in the range 0-31.
+Examples: "PA03", PD31".
+
+Pin numbers are the MCU port numbers in the range::
+
+    PA0..PA31:  0..31
+    PB0..PB31: 32..63
+    PC0..PC31: 64..95
+    PD0..PD31: 96..127
+
+Note: On Adafruit Feather and ItsyBity boards, pin D5 is connected to an external
+gate output and can therefore only be used as input.
+
+UART (serial bus)
+-----------------
+
+See :ref:`machine.UART <machine.UART>`. ::
+
+    # Use UART 3 on a ItsyBitsy M4 board
+    from machine import UART
+
+    uart3 = UART(3, tx=Pin(1), rx=Pin(0), baudrate=115200)
+    uart3.write('hello')  # write 5 bytes
+    uart3.read(5)         # read up to 5 bytes
+
+The SAMD21/SAMD51 MCUs have up to eight hardware so called SERCOM devices, which can be used as UART,
+SPI or I2C device, but not every MCU variant and board exposes all
+TX and RX pins for users. For the assignment of Pins to devices and UART signals,
+refer to the :ref:`SAMD pinout <samd_pinout>`.
+
+PWM (pulse width modulation)
+----------------------------
+
+Up to five timer device of the SAMD21/SAMD51 MCUs are used for creating PWM signals.
+
+The PWM functions are provided by the :ref:`machine.PWM <machine.PWM>` class.
+It supports all basic methods listed for that class. ::
+
+    # Samples for Adafruit ItsyBitsy M4 Express
+
+    from machine import Pin, PWM
+
+    pwm = PWM(Pin(7))      # create PWM object from a pin
+    pwm.freq()             # get current frequency
+    pwm.freq(1000)         # set frequency
+    pwm.duty_u16()         # get current duty cycle, range 0-65535
+    pwm.duty_u16(200)      # set duty cycle, range 0-65535
+    pwm.deinit()           # turn off PWM on the pin
+
+    pwm                    # show the PWM objects properties
+
+
+PWM Constructor
+```````````````
+
+.. class:: PWM(dest, freq, duty_u16, duty_ns, *, invert, device)
+  :noindex:
+
+    Construct and return a new PWM object using the following parameters:
+
+      - *dest* is the Pin object on which the PWM is output.
+
+    PWM objects are provided by TCC timer module. The TCC timer modules have up
+    to six channels and eight outputs. All channels of a module run at the same
+    frequency, but allow for different duty cycles. Outputs are assigned to channels
+    in modulo-n fashion, where n is the number of channels. Outputs of a channel
+    have the same frequency and duty rate, but may have different polarity.
+    So if for instance a module has four channels, output 0 and 4, 1 and 5,
+    2 and 6, 3, and 7 share the same frequency and duty rate.
+
+    Only one of *duty_u16* and *duty_ns* should be specified at a time.
+
+    Keyword arguments:
+
+      - *freq* should be an integer which sets the frequency in Hz for the
+        PWM cycle. The valid frequency range is 1 Hz to 24 MHz.
+      - *duty_u16* sets the duty cycle as a ratio ``duty_u16 / 65536``.
+        The duty cycle of a X channel can only be changed, if the A and B channel
+        of the respective submodule is not used. Otherwise the duty_16 value of the
+        X channel is 32768 (50%).
+      - *duty_ns* sets the pulse width in nanoseconds. The limitation for X channels
+        apply as well.
+      - *invert*\=True|False. Setting a bit inverts the respective output.
+      - *device*\=n Use TCC module n if available. At some pins two TCC modules could be
+        used. If not device is mentioned, the software tries to use a module which is not yet
+        used for a PWM signal. But if pins shall have the same frequency and/or duty cycle
+        to be changed synchronously, they must be driven by the same TCC module.
+
+PWM Methods
+```````````
+
+The methods are identical to the generic :ref:`machine.PWM <machine.PWM>` class,
+with additional keyword arguments to the init() method, matchings those of the constructor.
+
+PWM Pin Assignment
+``````````````````
+
+Pins are specified in the same way as for the Pin class.  For the assignment of Pins
+to PWM signals, refer to the :ref:`SAMD pinout <samd_pinout>`.
+
+ADC (analog to digital conversion)
+----------------------------------
+
+On the SAMD21/SAMD51 ADC functionality is available on Pins labelled 'Ann'.
+
+Use the :ref:`machine.ADC <machine.ADC>` class::
+
+    from machine import ADC
+
+    adc0 = ADC(Pin("A0"))            # create ADC object on ADC pin, average=16
+    adc0.read_u16()                  # read value, 0-65536 across voltage range 0.0v - 3.3v
+    adc1 = ADC(Pin("A1"), average=1) # create ADC object on ADC pin, average=1
+
+The resolution of the ADC is 12 bit with 12 bit accuracy, irrespective of the
+value returned by read_u16(). If you need a higher resolution or better accuracy, use
+an external ADC.
+
+ADC Constructor
+```````````````
+
+.. class:: ADC(dest, *, average=16)
+  :noindex:
+
+    Construct and return a new ADC object using the following parameters:
+
+      - *dest* is the Pin object on which the ADC is output.
+
+    Keyword arguments:
+
+      - *average* is used to reduce the noise. With a value of 16 the LSB noise is about 1 digit.
+
+DAC (digital to analog conversion)
+----------------------------------
+
+The DAC class provides a fast digital to analog conversion. Usage example::
+
+    from machine import DAC
+
+    dac0 = DAC(0)                    # create DAC object on DAC pin A0
+    dac0.write(1023)                 # write value, 0-4095 across voltage range 0.0v - 3.3v
+    dac1 = DAC(1)                    # create DAC object on DAC pin A1
+    dac1.write(2000)                 # write value, 0-4095 across voltage range 0.0v - 3.3v
+
+The resolution of the DAC is 12 bit for SAMD51 and 10 bit for SAMD21. SAMD21 devices
+have 1 DAC channel at GPIO PA02, SAMD51 devices have 2 DAC channels at GPIO PA02 and PA05.
+
+Software SPI bus
+----------------
+
+Software SPI (using bit-banging) works on all pins, and is accessed via the
+:ref:`machine.SoftSPI <machine.SoftSPI>` class. ::
+
+    from machine import Pin, SoftSPI
+
+    # construct a SoftSPI bus on the given pins
+    # polarity is the idle state of SCK
+    # phase=0 means sample on the first edge of SCK, phase=1 means the second
+    spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(7), mosi=Pin(9), miso=Pin(10))
+
+    spi.init(baudrate=200000) # set the baud rate
+
+    spi.read(10)            # read 10 bytes on MISO
+    spi.read(10, 0xff)      # read 10 bytes while outputting 0xff on MOSI
+
+    buf = bytearray(50)     # create a buffer
+    spi.readinto(buf)       # read into the given buffer (reads 50 bytes in this case)
+    spi.readinto(buf, 0xff) # read into the given buffer and output 0xff on MOSI
+
+    spi.write(b'12345')     # write 5 bytes on MOSI
+
+    buf = bytearray(4)      # create a buffer
+    spi.write_readinto(b'1234', buf) # write to MOSI and read from MISO into the buffer
+    spi.write_readinto(buf, buf) # write buf to MOSI and read MISO back into buf
+
+The highest supported baud rate is 500000.
+
+Hardware SPI bus
+----------------
+
+The SAMD21/SAMD51 MCUs have up to eight hardware so called SERCOM devices, which can be used as UART,
+SPI or I2C device, but not every MCU variant and board exposes all
+signal pins for users.  Hardware SPI is accessed via the
+:ref:`machine.SPI <machine.SPI>` class and has the same methods as software SPI above::
+
+    from machine import SPI
+
+    spi = SPI(1, sck=Pin("SCK"), mosi=Pin("MOSI"), miso=Pin("MISO"), baudrate=10000000)
+    spi.write('Hello World')
+
+If miso is not specified, it is not used. For the assignment of Pins to SPI devices and signals, refer to
+:ref:`SAMD pinout <samd_pinout>`.
+
+Note: Even if the highest reliable baud rate at the moment is about 24 Mhz,
+setting a baud rate will not always result in exactly that frequency, especially
+at high baud rates.
+
+Software I2C bus
+----------------
+
+Software I2C (using bit-banging) works on all output-capable pins, and is
+accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
+
+    from machine import Pin, SoftI2C
+
+    i2c = SoftI2C(scl=Pin(10), sda=Pin(11), freq=100000)
+
+    i2c.scan()              # scan for devices
+
+    i2c.readfrom(0x3a, 4)   # read 4 bytes from device with address 0x3a
+    i2c.writeto(0x3a, '12') # write '12' to device with address 0x3a
+
+    buf = bytearray(10)     # create a buffer with 10 bytes
+    i2c.writeto(0x3a, buf)  # write the given buffer to the slave
+
+The highest supported freq is 400000.
+
+Hardware I2C bus
+----------------
+
+The SAMD21/SAMD51 MCUs have up to eight hardware so called SERCOM devices,
+which can be used as UART, SPI or I2C device, but not every MCU variant
+and board exposes all signal pins for users.
+For the assignment of Pins to devices and I2C signals, refer to :ref:`SAMD pinout <samd_pinout>`.
+
+Hardware I2C is accessed via the :ref:`machine.I2C <machine.I2C>` class and
+has the same methods as software SPI above::
+
+    from machine import I2C
+
+    i2c = I2C(2, scl=Pin("SCL"), sda=Pin("SDA"), freq=400_000)
+    i2c.writeto(0x76, b"Hello World")
+
+OneWire driver
+--------------
+
+The OneWire driver is implemented in software and works on all pins::
+
+    from machine import Pin
+    import onewire
+
+    ow = onewire.OneWire(Pin(12)) # create a OneWire bus on GPIO12
+    ow.scan()                     # return a list of devices on the bus
+    ow.reset()                    # reset the bus
+    ow.readbyte()                 # read a byte
+    ow.writebyte(0x12)            # write a byte on the bus
+    ow.write('123')               # write bytes on the bus
+    ow.select_rom(b'12345678')    # select a specific device by its ROM code
+
+There is a specific driver for DS18S20 and DS18B20 devices::
+
+    import time, ds18x20
+    ds = ds18x20.DS18X20(ow)
+    roms = ds.scan()
+    ds.convert_temp()
+    time.sleep_ms(750)
+    for rom in roms:
+        print(ds.read_temp(rom))
+
+Be sure to put a 4.7k pull-up resistor on the data line.  Note that
+the ``convert_temp()`` method must be called each time you want to
+sample the temperature.
+
+DHT driver
+----------
+
+The DHT driver is implemented in software and works on all pins::
+
+    import dht
+    import machine
+
+    d = dht.DHT11(machine.Pin(4))
+    d.measure()
+    d.temperature() # eg. 23 (°C)
+    d.humidity()    # eg. 41 (% RH)
+
+    d = dht.DHT22(machine.Pin(4))
+    d.measure()
+    d.temperature() # eg. 23.6 (°C)
+    d.humidity()    # eg. 41.3 (% RH)
+
+Be sure to have a 4.7k pull-up resistor on the data line.  Some
+DHT modules may already have one.
+
+Driving an APA102 LED
+---------------------
+
+The APA102 on some Adafruit boards can be controlled using SoftSPI::
+
+    from machine import SoftSPI, Pin
+    # create the SPI object. miso can be any unused pin.
+    spi=SoftSPI(sck=Pin(25), mosi=Pin(26), miso=Pin(14))
+
+    # define a little function that writes the data with
+    # preamble and postfix
+    def write(red, green, blue):
+        spi.write(b"\x00\x00\x00\x00\xff")
+        spi.write(bytearray((blue, green, red)))
+        spi.write(b"\xff\xff\xff")
+
+    # set the LED to red
+    write(128, 0, 0)
+
+Since SoftSPI does not allow miso to be undefined, miso has to be
+assigned to an otherwise unused pin.
+
+Driving a Neopixel LED
+----------------------
+
+The built-in machine.bitstream() method supports driving Neopixel LEDs in combination
+with the Neopixel driver from the MicroPython driver library::
+
+    import neopixel
+    import machine
+
+    # 1 LED connected to Pin D8 on Adafruit Feather boards
+    p = machine.Pin(8, machine.Pin.OUT)
+    n = neopixel.NeoPixel(p, 1)
+
+    # set the led to red.
+    n[0] = (128, 0, 0)
+
+    # Update the LED.
+    n.write()
+
+machine.bitstream() is set up for a SAMD21 clock frequency of 48MHz and a SAMD51
+clock frequency of 120 MHz. At other clock frequencies, the timing will not fit.
+
+Transferring files
+------------------
+
+Files can be transferred to the SAMD21/SAMD51 devices for instance with the
+:ref:`mpremote <mpremote>` tool. See the MicroPython forum for community-supported
+alternatives to transfer files to an SAMD21/SAMD51 board, like rshell or Thonny.
diff --git a/docs/samd/tutorial/intro.rst b/docs/samd/tutorial/intro.rst
new file mode 100644
index 000000000..40038f4a7
--- /dev/null
+++ b/docs/samd/tutorial/intro.rst
@@ -0,0 +1,84 @@
+.. _samd_intro:
+
+Getting started with MicroPython on the SAMD
+==============================================
+
+Using MicroPython is a great way to get the most of your SAMD board.  And
+vice versa, the SAMD chip is a great platform for using MicroPython.  This
+tutorial will guide you through setting up MicroPython, getting a prompt, using
+the hardware peripherals, and controlling some external components.
+
+Let's get started!
+
+Requirements
+------------
+
+The first thing you need is a board with an SAMD chip.  The MicroPython
+software supports the SAMD chip itself and any board should work.  The main
+characteristic of a board is how the GPIO pins are connected to the outside
+world, and whether it includes a built-in USB-serial converter to make the
+UART available to your PC.
+
+Names of pins will be given in this tutorial using the board names ("D0")
+and it should be straightforward to find which pin this corresponds to on your
+particular board.
+
+Powering the board
+------------------
+
+If your board has a USB connector on it then most likely it is powered through
+this when connected to your PC.  Otherwise you will need to power it directly.
+Please refer to the documentation for your board for further details.
+
+Getting the firmware
+--------------------
+
+Firmware versions are provided at the
+`MicroPython download page <https://micropython.org/download/?port=samd>`_.
+You can download the most recent MicroPython firmware .uf2 file to load
+onto your SAMD device.  From that download page you have two main choices:
+
+* stable firmware builds
+* daily firmware builds
+
+If you are just starting with MicroPython, the best bet is to go for the stable
+firmware builds. If you are an advanced, experienced MicroPython SAMD user
+who would like to follow development closely and help with testing new
+features, there are daily builds. They run through the same rigid internal
+test sequence as the stable builds, but the firmware features may change.
+
+Deploying the firmware
+----------------------
+
+Once you have the MicroPython firmware you need to load it onto your
+SAMD device. Most of the boards support the following easy procedure for
+firmware upload.
+
+- Connect the board by an USB-A/USB-Micro cable to your PC.
+- Push the reset button twice. Then, a drive should pop up at the
+  PC's file manager. Many boards have a on-board RGB LED, which first lights up
+  red, and then changes it's colour to green. The timing of the double push is
+  sometimes tricky. So you may have to try to get the proper rhythm.
+- Copy the .uf2 file to that newly opened drive. A LED on the board may
+  flash a while. When the copy is finished, the board drive will disappear and the
+  RGB led will turn from green to the initial state.
+
+Serial prompt
+-------------
+
+Once you have the firmware on the device you can access the REPL (Python prompt)
+over USB.
+
+From there you can follow the SAMD tutorial.
+
+Troubleshooting installation problems
+-------------------------------------
+
+If you experience problems during flashing or with running firmware immediately
+after it, here are some troubleshooting recommendations:
+
+* Be aware of and try to exclude hardware problems.  There are two common
+  problems: bad power source quality, and worn-out/defective Flash ROM.
+  Speaking of power source, not just raw amperage is important, but also low
+  ripple and noise/EMI in general.  The most reliable and convenient power
+  source is a USB port.