Skip to content

Commit 016ae19

Browse files
robert-hhdpgeorge
robert-hh
authored and
dpgeorge
committed
docs/samd: Update the SAMD documentation describing default IDs/pins.
Changes are: - Add the RX/TX pins to the table. In most cases these are the D0/D1 pins. - Document the ability for the instantiation of the default devices without submitting ID or pins. - Improve the example script creating the pin list to show multiple name assigments to the same pin. - Fix errors in the pinout document. Signed-off-by: robert-hh <[email protected]>
1 parent b9b4f1b commit 016ae19

File tree

2 files changed

+79
-28
lines changed

2 files changed

+79
-28
lines changed

‎docs/samd/pinout.rst‎

Lines changed: 53 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,11 @@ Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
4141
35 PB03 FLASH_MISO 3 11 - 5/1 6/1 -
4242
54 PB22 FLASH_MOSI 6 - - 5/2 7/0 -
4343
55 PB23 FLASH_SCK 7 - - 5/3 7/1 -
44+
11 PA11 RX 11 19 0/3 2/3 1/1 0/3
45+
10 PA10 TX 10 18 0/2 2/2 1/0 0/2
4446
12 PA12 MISO 12 - 2/0 4/0 2/0 0/6
45-
42 PB10 MOSI 10 - - 4/2 5/0 0/4
46-
43 PB11 SCK 11 - - 4/3 5/1 0/5
47+
42 PA12 MOSI 10 - - 4/2 5/0 0/4
48+
43 PA13 SCK 11 - - 4/3 5/1 0/5
4749
23 PA23 SCL 7 - 3/1 5/1 4/1 0/5
4850
22 PA22 SDA 6 - 3/0 5/0 4/0 0/4
4951
30 PA30 SWCLK 10 - - 1/2 1/0 -
@@ -127,7 +129,7 @@ Examples for Adafruit ItsyBitsy M0 Express:
127129
- SPI 1 at pins D11/D12/D13
128130
- SPI 2 at pins D0/D4/D1
129131
- SPI 3 at pins D11/D12/D13
130-
- SPI 4 at Pin MOSI/MISO/SCK This is the default SPI device at the MOSI/MISO/SCK labelled pins.
132+
- SPI 2 at Pin MOSI/MISO/SCK This is the default SPI device at the MOSI/MISO/SCK labelled pins.
131133

132134
or other combinations.
133135

@@ -169,6 +171,8 @@ Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
169171
22 PA22 D13 6 - - 3/0 5/1 4/0 1/6 0/2
170172
34 PB02 DOTSTAR_CLK 2 14 - - 5/0 6/0 2/2 -
171173
35 PB03 DOTSTAR_DATA 9 15 - - 5/1 6/1 - -
174+
16 PA16 RX 0 - - 1/0 3/1 2/0 1/0 0/4
175+
17 PA17 TX 1 - - 1/1 3/0 2/1 1/1 0/5
172176
55 PB23 MISO 7 - - 1/3 5/3 7/1 - -
173177
0 PA00 MOSI 0 - - - 1/0 2/0 - -
174178
43 PB11 QSPI_CS 12 - - - 4/3 5/1 0/5 1/1
@@ -235,7 +239,7 @@ The I2C devices and signals must be chosen according to the following rules:
235239
- The SDA signal must be at a Pin with pad numbers 0.
236240
- The SCL signal must be at a Pin with pad numbers 1.
237241

238-
Examples for Adafruit ItsyBitsy M0 Express:
242+
Examples for Adafruit ItsyBitsy M4 Express:
239243

240244
- I2C 0 at pins A3/A4
241245
- I2C 1 at pins D0/D1
@@ -253,7 +257,7 @@ The SPI devices and signals must be chosen according to the following rules:
253257
- The following pad number pairs are suitable for MOSI/SCK: 0/1 and 3/1.
254258
- The MISO signal must be at a Pin with a different pad number than MOSI or SCK.
255259

256-
Examples for Adafruit ItsyBitsy M0 Express:
260+
Examples for Adafruit ItsyBitsy M4 Express:
257261

258262
- SPI 1 at Pin MOSI/MISO/SCK This is the default SPI device at the MOSI/MISO/SCK labelled pins.
259263
- SPI 3 at pins D13/D11/D12
@@ -296,6 +300,8 @@ Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
296300
21 PA21 D11 5 - - 5/3 3/3 7/1 1/5 0/1
297301
22 PA22 D12 6 - - 3/0 5/1 4/0 1/6 0/2
298302
23 PA23 D13 7 - - 3/1 5/0 4/1 1/7 0/3
303+
49 PB17 RX 1 - - 5/1 - 6/1 3/1 0/5
304+
48 PB16 TX 0 - - 5/0 - 6/0 3/0 0/4
299305
54 PB22 MISO 22 - - 1/2 5/2 7/0 - -
300306
55 PB23 MOSI 7 - - 1/3 5/3 7/1 - -
301307
35 PB03 NEOPIXEL 9 15 - - 5/1 6/1 - -
@@ -381,6 +387,8 @@ Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
381387
8 PA08 FLASH_MOSI - 8 2 0/0 2/1 0/0 0/0 1/4
382388
42 PB10 FLASH_SCK 10 - - - 4/2 5/0 0/4 1/0
383389
10 PA10 FLASH_WP 10 10 - 0/2 2/2 1/0 0/2 1/6
390+
23 PA23 RX 7 - - 3/1 5/0 4/1 1/7 0/3
391+
22 PA22 TX 6 - - 3/0 5/1 4/0 1/6 0/2
384392
14 PA14 MISO 14 - - 2/2 4/2 3/0 2/0 1/2
385393
12 PA12 MOSI 12 - - 2/0 4/1 2/0 0/6 1/2
386394
54 PB22 NEOPIXEL 22 - - 1/2 5/2 7/0 - -
@@ -429,6 +437,13 @@ Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
429437
5 PA05 A9_D9 5 5 - 0/1 0/1 -
430438
6 PA06 A10_D10 6 6 - 0/2 1/0 -
431439
18 PA18 RX_LED 2 - 1/2 3/2 3/0 0/2
440+
41 PB09 RX 9 3 - 4/1 4/1 -
441+
40 PB08 TX 8 2 - 4/0 4/0 -
442+
8 PA08 SDA - 16 0/0 2/0 0/0 1/2
443+
9 PA09 SCL 9 17 0/1 2/1 0/1 1/3
444+
6 PA06 MOSI 6 6 - 0/2 1/0 -
445+
5 PA05 MISO 5 5 - 0/1 0/1 -
446+
7 PA07 SCK 7 7 - 0/3 1/1 -
432447
30 PA30 SWCLK 10 - - 1/2 1/0 -
433448
31 PA31 SWDIO 11 - - 1/3 1/1 -
434449
19 PA19 TX_LED 3 - 1/3 3/3 3/1 0/3
@@ -503,6 +518,8 @@ Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
503518
43 PB11 SCK 11 - - 4/3 5/1 0/5
504519
23 PA23 SCL 7 - 3/1 5/1 4/1 0/5
505520
22 PA22 SDA 6 - 3/0 5/0 4/0 0/4
521+
11 PA11 RX 11 19 0/3 2/3 1/1 0/3
522+
10 PA10 TX 10 18 0/2 2/2 1/0 0/2
506523
30 PA30 SWCLK 10 - - 1/2 1/0 -
507524
31 PA31 SWDIO 11 - - 1/3 1/1 -
508525
24 PA24 USB_DM 12 - 3/2 5/2 5/0 1/2
@@ -518,9 +535,9 @@ Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
518535

519536
The default devices at the board are:
520537

521-
- UART 5 at pins PB23/PB22, labelled RX/TX
538+
- UART 2 at pins PA11/PA10, labelled RX/TX
522539
- I2C 3 at pins PA22/PA23, labelled SDA/SCL
523-
- SPI 4 at pins PA10/PA12/PA11, labelled MOSI, MISO and SCK
540+
- SPI 4 at pins PB10/PA12/PB11, labelled MOSI, MISO and SCK
524541
- DAC output on pin PA02, labelled A0
525542

526543
Adafruit Trinket M0 pin assignment table
@@ -536,6 +553,13 @@ Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
536553
6 PA06 D4 6 6 - 0/2 1/0 -
537554
1 PA01 DOTSTAR_CLK 1 - - 1/1 2/1 -
538555
0 PA00 DOTSTAR_DATA 0 - - 1/0 2/0 -
556+
7 PA07 RX 7 7 - 0/3 1/1 -
557+
6 PA06 TX 6 6 - 0/2 1/0 -
558+
8 PA08 SDA - 16 0/0 2/0 0/0 1/2
559+
9 PA09 SCL 9 17 0/1 2/1 0/1 1/3
560+
6 PA06 MOSI 6 6 - 0/2 1/0 -
561+
9 PA09 MISO 9 17 0/1 2/1 0/1 1/3
562+
7 PA07 SCK 7 7 - 0/3 1/1 -
539563
10 PA10 LED 10 18 0/2 2/2 1/0 0/2
540564
30 PA30 SWCLK 10 - - 1/2 1/0 -
541565
31 PA31 SWDIO 11 - - 1/3 1/1 -
@@ -716,8 +740,10 @@ Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
716740
34 PB02 DOTSTAR_CLK 2 14 - - 5/0 6/0 2/2 -
717741
35 PB03 DOTSTAR_DATA 9 15 - - 5/1 6/1 - -
718742
15 PA15 LED 15 - - 2/3 4/3 3/1 2/1 1/3
719-
55 PB23 MISO 7 - - 1/3 5/3 7/1 - -
720-
54 PB22 MOSI 22 - - 1/2 5/2 7/0 - -
743+
16 PA16 RX 0 - - 1/0 3/1 2/0 1/0 0/4
744+
17 PA17 TX 1 - - 1/1 3/0 2/1 1/1 0/5
745+
55 PB23 MOSI 7 - - 1/3 5/3 7/1 - -
746+
54 PB22 MISO 22 - - 1/2 5/2 7/0 - -
721747
43 PB11 QSPI_CS 12 - - - 4/3 5/1 0/5 1/1
722748
8 PA08 QSPI_D0 - 8 2 0/0 2/1 0/0 0/0 1/4
723749
9 PA09 QSPI_D1 9 9 3 0/1 2/0 0/1 0/1 1/5
@@ -893,6 +919,8 @@ Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
893919
11 PA11 FLASH_MISO 11 11 - 0/3 2/3 1/1 0/3 1/7
894920
8 PA08 FLASH_MOSI - 8 2 0/0 2/1 0/0 0/0 1/4
895921
9 PA09 FLASH_SCK 9 9 3 0/1 2/0 0/1 0/1 1/5
922+
13 PA13 RX 13 - - 2/1 4/0 2/1 0/7 1/3
923+
12 PA12 TX 12 - - 2/0 4/1 2/0 0/6 1/2
896924
43 PB11 MISO 12 - - - 4/3 5/1 0/5 1/1
897925
44 PB12 MOSI 12 - - 4/0 - 4/0 3/0 0/0
898926
55 PB23 RXD 7 - - 1/3 5/3 7/1 - -
@@ -931,7 +959,7 @@ Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
931959
The default devices at the board are:
932960

933961
- UART 2 at pins PA13/PA12, labelled RXD/TXD
934-
- I2C 5 at pins PA22/PA23, labelled SDA/SCL
962+
- I2C 3 at pins PA22/PA23, labelled SDA/SCL
935963
- SPI 4 at pins PB12/PB11/PB13, labelled MOSI, MISO and SCK
936964
- DAC output on pins PA02 and PA05, labelled A0 and A4
937965

@@ -1163,22 +1191,22 @@ The tables shown above were created with small a Python script running on the ta
11631191
else:
11641192
return "zzzzzzz%03d" % i[0]
11651193

1166-
def table(num=127, sort=True):
1167-
pintbl = []
1168-
inv_bd = {v: k for k, v in Pin.board.__dict__.items()}
1169-
for i in range(num):
1170-
try:
1171-
p = Pin(i)
1172-
pi = pininfo(p)
1173-
if p in inv_bd.keys():
1174-
name = inv_bd[p]
1175-
else:
1176-
name = ""
1177-
pintbl.append((i, name, pininfo(i)))
1178-
except:
1179-
pass
1180-
# print("not defined")
1194+
def pinnum(p):
1195+
return (ord(p[1]) - ord("A")) * 32 + int(p[2:])
11811196

1197+
def table(num = 127, sort=True):
1198+
pintbl = []
1199+
pinlist = []
1200+
for name in Pin.board.__dict__.keys():
1201+
p = Pin(name)
1202+
pi = pininfo(p)
1203+
pintbl.append((pinnum(pi[0]), name, pi))
1204+
pinlist.append(p)
1205+
for pc in Pin.cpu.__dict__.keys():
1206+
p = Pin(pc)
1207+
pi = pininfo(p)
1208+
if not p in pinlist:
1209+
pintbl.append((pinnum(pi[0]), "", pi))
11821210
if sort:
11831211
pintbl.sort(key=tblkey)
11841212
for item in pintbl:

‎docs/samd/quickref.rst‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -163,10 +163,15 @@ See :ref:`machine.UART <machine.UART>`. ::
163163
uart3.write('hello') # write 5 bytes
164164
uart3.read(5) # read up to 5 bytes
165165

166+
uart = UART() # Use the default values for id, rx and tx.
167+
uart = UART(baudrate=9600) # Use the default UART and set the baudrate
168+
166169
The SAMD21/SAMD51 MCUs have up to eight hardware so called SERCOM devices, which can be used as UART,
167170
SPI or I2C device, but not every MCU variant and board exposes all
168171
TX and RX pins for users. For the assignment of Pins to devices and UART signals,
169-
refer to the :ref:`SAMD pinout <samd_pinout>`.
172+
refer to the :ref:`SAMD pinout <samd_pinout>`. If the id, rx or tx pins are not specified,
173+
the default values are used. The first positional argument (if given) is assumed to be the UART id.
174+
If the baudrate is changed and the UART id is omitted, it must be set using the baudrate keyword.
170175

171176
PWM (pulse width modulation)
172177
----------------------------
@@ -373,8 +378,18 @@ signal pins for users. Hardware SPI is accessed via the
373378
spi = SPI(1, sck=Pin("SCK"), mosi=Pin("MOSI"), miso=Pin("MISO"), baudrate=10000000)
374379
spi.write('Hello World')
375380

376-
If miso is not specified, it is not used. For the assignment of Pins to SPI devices and signals, refer to
377-
:ref:`SAMD pinout <samd_pinout>`.
381+
For the assignment of Pins to SPI devices and signals, refer to
382+
:ref:`SAMD pinout <samd_pinout>`. If the id, miso, mosi or sck pins are not specified,
383+
the default values are used. So it is possible to create the SPI object as::
384+
385+
from machine import SPI
386+
spi = SPI() # Use the default device and default baudrate
387+
spi = SPI(baudrate=12_000_000) # Use the default device and change the baudrate
388+
389+
If the MISO signal shall be omitted, it must be defined as miso=None.
390+
The first positional argument (if given) is assumed to be the SPI id.
391+
If the baudrate is changed while the SPI id is omitted, it must be
392+
set using the baudrate keyword.
378393

379394
Note: Even if the highest reliable baud rate at the moment is about 24 Mhz,
380395
setting a baud rate will not always result in exactly that frequency, especially
@@ -407,6 +422,7 @@ The SAMD21/SAMD51 MCUs have up to eight hardware so called SERCOM devices,
407422
which can be used as UART, SPI or I2C device, but not every MCU variant
408423
and board exposes all signal pins for users.
409424
For the assignment of Pins to devices and I2C signals, refer to :ref:`SAMD pinout <samd_pinout>`.
425+
If the id, scl or sda pins are not specified, the default values are used.
410426

411427
Hardware I2C is accessed via the :ref:`machine.I2C <machine.I2C>` class and
412428
has the same methods as software SPI above::
@@ -416,6 +432,13 @@ has the same methods as software SPI above::
416432
i2c = I2C(2, scl=Pin("SCL"), sda=Pin("SDA"), freq=400_000)
417433
i2c.writeto(0x76, b"Hello World")
418434

435+
i2c2 = I2C() # Use the default values for id, scl and sda.
436+
i2c2 = I2C(freq=100_000) # Use the default device and set freq.
437+
438+
The first positional argument (if given) is assumed to be the I2C id.
439+
If the freq is changed and the I2C id is omitted, it must be set using
440+
the freq keyword.
441+
419442
OneWire driver
420443
--------------
421444

0 commit comments

Comments
 (0)