diff --git a/ports/samd/README.md b/ports/samd/README.md index 4b434963d9..49e967102e 100644 --- a/ports/samd/README.md +++ b/ports/samd/README.md @@ -1,146 +1,61 @@ Port of MicroPython to Microchip SAMD MCUs ========================================== -Supports SAMD21 and SAMD51. - -## Features: - -### REPL - -- REPL over USB VCP -- REPL over USART using board specified USART pins (initialised on startup). - - The USART Pins are board specific, defined in `boards/$(BOARD)/mpconfigboard.h`, - and set at compile time. See the table below. At this stage, the USART cannot be - moved to different pins unless `mpconfigboard.h` is edited and the port recompiled. - - Two USART functions are accessible through MicroPython: - - `uart_init()`. The 'C' function behind this function is what initialises the - USART on startup. Calling this function in MicroPython resets any other peripheral - operating on these pins and reconnects the USART SERCOM to the designated pins. - - `uart_deinit()`. This simply 'disconnects' the SERCOM from the pins. The USART - remains operating over USB VCP to maintain access to the REPL. - -### Boards - -| Board | USART | LFS1 Flash size | Tested | -| ------------------------------------------------------------ | ----------------------------------------------------------- | --------------- | ------ | -| ADAFRUIT_FEATHER_M0_EXPRESS | Tx=PA10=SERCOM0/PAD[2], Rx=PA11=SERCOM0/PAD[3] | 64k | No | -| ADAFRUIT_ITSYBITSY_M4_EXPRESS | Tx=TX_D1=PA17=SERCOM3/PAD[0], Rx=RX_D0=PA16=SERCOM3/PAD[1] | 128k | No | -| ADAFRUIT_TRINKET_M0 | Tx=D4=PA06=SERCOM0/PAD[2], Rx=D3=PA07=SERCOM0/PAD[3] | 64k | No | -| MINISAM_M4 | Tx=TX_D1=PA17=SERCOM3/PAD[0], Rx=RX_D0=PA16=SERCOM3/PAD[1] | 128k | No | -| SAMD21_XPLAINED_PRO | Tx=PA10=SERCOM0/PAD[2], Rx=PA11=SERCOM0/PAD[3] | 64k | No | -| SEEED_WIO_TERMINAL | Tx=BCM14=PB27=SERCOM2/PAD[0], Rx=BCM15=PB26=SERCOM2/PAD[1] | 128k | Yes | -| SEEED_XIAO | Tx=A6=PB8=SERCOM4/PAD[0], Rx=A7=PB9=SERCOM4/PAD[1] | 64k | Yes | - -Note: all USARTs are set to: async, 8 bit, 1 stop bit, no parity, 115200 bps. - -### Modules - -- Internal modules and functions: - -`>>>help('modules')` -`__main__ micropython uheapq ustruct` -`_boot samd uio usys` -`_uasyncio uarray ujson utime` -`builtins uasyncio uos uzlib` -`gc ubinascii urandom` -`machine uctypes ure` -`Plus any modules on the filesystem` - -#### Flash - -- Internal Flash Block Device `samd.Flash()` initialised with littlefs1 in frozen module '`_boot.py`'. - -- **No external SPI Flash driver** (ToDo). - -- Block Device size is set in `ports/samd/boards/$(BOARD)/mpconfigboard.h` : - - - SAMD21: (eg; SEEED_XIAO): 64k `0xFFFF` - - * SAMD51: (eg; M4's): 128k `0x1FFFF` - -#### Pins & LEDs - -##### `machine.Pin()` class. - -- GPIO methods & constants: - - value IN OUT PULL_DOWN - PULL_UP high init low - off on toggle - -- Each board has its own pin numbering scheme, so please see the table below (the - structure is defined in`boards/$(BOARD)/pins.c`) for pin numbers referenced - (index) by 'Pin'. Eg; `SEEED_XIAO/pins.c`: `{{&machine_pin_type}, PIN_PA02}, // A0/D0` - means MicroPython `Pin(0)` is SEEED_XIAO pin "A0/D0" on SAMD21G18A PortA, Pin2. - -- Note: on the SEEED_XIAO, if the TX & TX pins are used by the `Pin()` class, the `Pin()` - initialisation disconnects the pins from the SERCOM similar to the way - `machine.uart_deinit()` does. - -| MicroPython Pin() | SAMD51 Pin#/ ItsyBitsy_M4 | SAMD21 Pin#/ Feather_M0 | SAMD21 Pin#/ Xplained Pro | SAMD21 Pin#/ Trinket_M0 | SAMD51 Pin#/ Minisam | SAMD21 Pin#/ SEEED_XIAO | SAMD51 Pin#/ SEEED_WIO_TERMINAL | -| ----------------- | -------------------------- | ------------------------ | ----------------------------------- | ------------------------ | -------------------- | ----------------------- | ------------------------------------- | -| Pin(0) | PA16/ RX_D0 | PA11/ D0 | PB00/ PIN3_ADC(+) (ext1) | PA08/ D0 | PA02/ A0,D9 | PA02 / A0/D0 | PB08 / A0/D0 | -| Pin(1) | PA17/ TX_D1 | PA10/ D1 | PB01/ PIN4_ADC(-) (ext1) | PA02/ D1 | PB08/ A1,D10 | PA04 / A1/D1 | PB09 / A1/D1 | -| Pin(2) | PA07/ D2 | PA14/ D2 | PB06/ PIN5_GPIO (ext1) | PA09/ D2 | PB09/ A2,D11 | PA10 / A2/D2 | PA07 / A2/D2 | -| Pin(3) | PB22/ D3 | PA09/ D3/ | PB07/ PIN6_GPIO (ext1) | PA07/ D3/ RxD | PA04/ A3,D12 | PA11 / A3/D3 | PB04 / A3/D3 | -| Pin(4) | PA14/ D4 | PA08/ D4/ | PB02/ PIN7_PWM(+) (ext1) | PA06/ D4/ TxD | PA05/ A4,D13 | PA08 / A4/D4 | PB05 / A4/D4 | -| Pin(5) | PA15/ D5 | PA15/ D5 | PB03/ PIN8_PWM(-) (ext1) | | PA06/ A5 | PA09 / A5/D5 | PB06 / A5/D5 | -| Pin(6) | -1/ D6 | PA20/ D6 | PB04/ PIN9_IRQ/GPIO (ext1) | | PA16/ RX_D0 | PB08 / A6/D6/TX | PA04 / A6/D6 | -| Pin(7) | PA18/ D7 | PA21/ D7 | PB05/ PIN10_SPI_SS_B/GPIO (ext1) | | PA17/ TX_D1 | PB09 / A7/D7/RX | PB07 / A7/D7 | -| Pin(8) | -1/ D8 | PA06/ D8/ | PA08/ PIN11_TWI_SDA (ext1) | | PA07/ D2,A6 | PA07 / A8/D8 | PA06 / A8/D8 | -| Pin(9) | PA19/ D9 | PA07/ D9/ | PA09/ PIN12_TWI_SCL (ext1) | | PA19/ D3 | PA05 / A9/D9 | PD08 / SWITCH_X | -| Pin(10) | PA20/ D10 | PA18/ D10 | PB09/ PIN13_UART_RX (ext1) | | PA20/ D4 | PA06 / A10/D10 | PD09 / SWITCH_Y | -| Pin(11) | PA21/ D11 | PA16/ D11 | PB08/ PIN14_UART_TX (ext1) | | PA21/ D5 | | PD10 / SWITCH_Z | -| Pin(12) | PA23/ D12 | PA19/ D12 | PA05/ PIN15_SPI_SS_A (ext1) | | PA00/ BUTTON | | PD12 / SWITCH_B | -| Pin(13) | PA22/ D13 | PA17/ D13/ | PA06/ PIN16_SPI_MOSI (ext1) | | | | PD20 / SWITCH_U | -| Pin(14) | PA02/ A0 | PA02/ A0 | PA04/ PIN17_SPI_MISO (ext1) | | | | PC26 / BUTTON_1 | -| Pin(15) | PA05/ A1 | PB08/ A1 | PA07/ PIN18_SPI_SCK (ext1) | | | | PC27 / BUTTON_2 | -| Pin(16) | PB08/ A2 | PB09/ A2 | PA10/ PIN3_ADC(+) (ext2) | | | | PC28 / BUTTON_3 | -| Pin(17) | PB09/ A3 | PA04/ A3/ | PA11/ PIN4_ADC(-) (ext2) | | | | PD11 / BUZZER_CTR | -| Pin(18) | PA04/ A4 | PA05/ A4/ | PA20/ PIN5_GPIO (ext2) | | | | PC14/ 5V_OUTPUT_CTR- '1'= 5V on hdr | -| Pin(19) | PA06/ A5 | PB02/ A5 | PA21/ PIN6_GPIO (ext2) | | | | PC15/ 3V3_OUTPUT_CTR- '0'= 3V3 on hdr | -| Pin(20) | | | PB12/ PIN7_PWM(+) (ext2) | | | | | -| Pin(21) | | | PB13/ PIN8_PWM(-) (ext2) | | | | | -| Pin(22) | | | PB14/ PIN9_IRQ/GPIO (ext2) | | | | | -| Pin(23) | | | PB15/ PIN10_SPI_SS_B/GPIO (ext2) | | | | | -| Pin(24) | | | -1 / PIN11_TWI_SDA already defined | | | | | -| Pin(25) | | | -1 / PIN12_TWI_SCL already defined | | | | | -| Pin(26) | | | PB11/ PIN13_UART_RX (ext2) | | | | | -| Pin(27) | | | PB10/ PIN14_UART_TX (ext2) | | | | | -| Pin(28) | | | PA17/ PIN15_SPI_SS_A (ext2) | | | | | -| Pin(29) | | | PA18/ PIN16_SPI_MOSI (ext2) | | | | | -| Pin(30) | | | PA16/ PIN17_SPI_MISO (ext2) | | | | | -| Pin(31) | | | PA19/ PIN18_SPI_SCK (ext2) | | | | | -| Pin(32) | | | PA02/ PIN3_ADC(+) (ext3) | | | | | -| Pin(33) | | | PA03/ PIN4_ADC(-) (ext3) | | | | | -| Pin(34) | | | -1/ PIN5_GPIO already defined | | | | | -| Pin(35) | | | PA15/ PIN6_GPIO; USER_BUTTON (ext3) | | | | | -| Pin(36) | | | PA12/ PIN7_PWM(+) (ext3) | | | | | -| Pin(37) | | | PA13/ PIN8_PWM(-) (ext3) | | | | | -| Pin(38) | | | PA28/ PIN9_IRQ/GPIO (ext3) | | | | | -| Pin(39) | | | PA27/ PIN10_SPI_SS_B/GPIO (ext3) | | | | | -| Pin(40) | | | -1/ PIN11_TWI_SDA already defined | | | | | -| Pin(41) | | | -1/ PIN12_TWI_SCL already defined | | | | | -| Pin(42) | | | -1/ PIN13_UART_RX already defined | | | | | -| Pin(43) | | | -1/ PIN14_UART_TX already defined | | | | | -| Pin(44) | | | PA15/ PIN6_GPIO; USER_BUTTON (ext3) | | | | | -| Pin(45) | | | PB22/ PIN16_SPI_MOSI (ext3) | | | | | -| Pin(46) | | | PB16/ PIN17_SPI_MISO (ext3) | | | | | -| Pin(47) | | | PB23/ PIN18_SPI_SCK (ext3) | | | | | - -##### `machine.LED()` class. - -- GPIO methods & constants: - -`value OUT high low` -`off on toggle` - -- As above, please see `boards/$(BOARD)/pins.c` for pin numbers referenced by 'LED'. -Eg; `SEEED_XIAO/pins.c`: `{{&machine_led_type}, PIN_PA17}, // W13` means MicroPython -`LED(0)` is SEEED_XIAO LED "W13" connected to SAMD21G18A PortA, Pin17. - -| MicroPython LED() | SAMD51 Pin#/ ItsyBitsy_M4 | SAMD21 Pin#/ Feather_M0 | SAMD21 Pin#/ Xplained Pro | SAMD21 Pin#/ Trinket_M0 | SAMD51 Pin#/ Minisam | SAMD21 Pin#/ SEEED_XIAO | SAMD51 Pin#/ SEEED_WIO_TERMINAL | -| ------------------ | -------------------------- | ------------------------ | -------------------------- | ------------------------ | --------------------- | ------------------------ | -------------------------------- | -| LED(0) | PA22/ D13/ user LED | PA17/ D13/ user LED | PB30/ USER_LED | PA10/ USER_LED | PA15/ LED | PA17 / W13 | PA15 / USER_LED (Blue) | -| LED(1) | | | | | | PA18 / RX_LED | PC05 / LCD_BACKLIGHT_CTR | -| LED(2) | | | | | | PA19 / TX_LED | | +Supports SAMD21 and SAMD51. For each supported device there is a +subdirectory in the `boards/` directory. + +The entry point for the specific port documentation is at +https://docs.micropython.org/en/latest/samd/quickref.html, which also +shows the assignment of IO-Functions to pins. The generic MicroPython +documentation applies for anything not specific for the SAM port. + +Due to the different flash sizes of SAMD21 and SAMD51 devices, the +coverage of MicroPython modules differ. Use help("modules") to tell, +which MicroPython modules are provided. + +Build instructions +------------------ + +Before building the firmware for a given board the MicroPython cross-compiler +must be built; it will be used to pre-compile some of the built-in scripts to +bytecode. The cross-compiler is built and run on the host machine, using: + + $ make -C mpy-cross + +This command should be executed from the root directory of this repository. +All other commands below should be executed from the ports/stm32/ directory. + +An ARM compiler is required for the build, along with the associated binary +utilities. The default compiler is `arm-none-eabi-gcc`, which is available for +Arch Linux via the package `arm-none-eabi-gcc`, for Ubuntu via instructions +[here](https://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa), or +see [here](https://launchpad.net/gcc-arm-embedded) for the main GCC ARM +Embedded page. The compiler can be changed using the `CROSS_COMPILE` variable +when invoking `make`. + +Next, the board to build must be selected. There is no default board. Any +of the names of the subdirectories in the `boards/` directory is a valid board. +The board name must be passed as the argument to `BOARD=` when invoking `make`. + +All boards require certain submodules to be obtained before they can be built. +The correct set of submodules can be initialised using (with +`ADAFRUIT_ITSYBITSY_M4_EXPRESS` as an example of the selected board): + + $ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS submodules + +Then to build the board's firmware run: + + $ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS clean + $ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS + +The above command produces binary images in the +`build-ADAFRUIT_ITSYBITSY_M4_EXPRESS/` subdirectory (or the equivalent +directory for the board specified). + +### Flashing the Firmware + +Most SAMD21 and SAMD51 boards have a built in firmware loader. To start it, push +the reset button of the boards twice. The speed varies a little bit. If the +firmware loader starts, a drive will appear in the file manager of your PC. +Copy the created `firmware.uf2` file to that drive. If the upload is finished, the +drive will disappear and the board will reboot.