Lephenixnoir
/
PythonExtra
1
0
Fork 2
Code Issues 9 Pull Requests 3 Projects Releases 2 Wiki Activity

samd/README: Update README to reflect recent changes to the port. 

Most of the content of README.md became obsolete and was replaced by the
documentation of MicroPython.  Instead, README.md now shows build
instructions like the other ports.
This commit is contained in:
robert-hh 2022-10-30 18:06:33 +01:00 committed by Damien George
parent b3ce059767
commit fadfc30547
1 changed files with 43 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
ports/samd/README.md
View File

@ -1,146 +1,61 @@
Port of MicroPython to Microchip SAMD MCUs
==========================================
Supports SAMD21 and SAMD51.
Supports SAMD21 and SAMD51. For each supported device there is a
subdirectory in the `boards/` directory.
## Features:
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.
### REPL
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.
- 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.
Build instructions
------------------
### Boards
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:
| 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 |
$ make -C mpy-cross
Note: all USARTs are set to: async, 8 bit, 1 stop bit, no parity, 115200 bps.
This command should be executed from the root directory of this repository.
All other commands below should be executed from the ports/stm32/ directory.
### Modules
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`.
- Internal modules and functions:
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`.
`>>>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`
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):
#### Flash
$ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS submodules
- Internal Flash Block Device `samd.Flash()` initialised with littlefs1 in frozen module '`_boot.py`'.
Then to build the board's firmware run:
- **No external SPI Flash driver** (ToDo).
$ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS clean
$ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS
- Block Device size is set in `ports/samd/boards/$(BOARD)/mpconfigboard.h` :
The above command produces binary images in the
`build-ADAFRUIT_ITSYBITSY_M4_EXPRESS/` subdirectory (or the equivalent
directory for the board specified).
- SAMD21: (eg; SEEED_XIAO): 64k `0xFFFF`
### Flashing the Firmware
* 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 | |
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.