circuitpython/ports/atmel-samd
Scott Shawcroft d32349cee8
Merge pull request #804 from dhalbert/boot_out_fixes
3.0: Handle bad power on reset.
2018-05-04 10:06:35 -07:00
..
asf4@02e264253c atmel-samd: Add rtc module support 2018-04-16 13:15:08 +02:00
asf4_conf atmel-samd: Fix M4 RTC and ItsyBitsy M4 definition 2018-04-19 14:42:03 -04:00
boards 3.0: add CircuitPlayground and HID to CPX frozen modules 2018-05-04 08:44:33 -04:00
common-hal Merge pull request #789 from tannewt/pdmin3 2018-05-02 19:59:20 -04:00
external_flash Add Feather M4 Express support. 2018-03-23 00:00:13 -07:00
freetouch@c3deba11eb Remove freetouch files that were accidentally checked in and 2018-03-28 14:04:53 -07:00
modules Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
supervisor Handle bad power on reset. 2018-05-03 23:43:02 -04:00
tools convert wrapper class to just a module 2018-04-24 13:28:26 -04:00
.gitattributes Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
.gitignore Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
Makefile Re-enable PDMIn without ASF and using the helpers added with 2018-05-01 14:35:43 -07:00
README.rst ambiguized directory paths 2018-03-30 22:44:16 +00:00
audio_dma.c Fix 8 bit recordings on CPX. 2018-05-02 15:15:25 -07:00
audio_dma.h Re-enable PDMIn without ASF and using the helpers added with 2018-05-01 14:35:43 -07:00
background.c Add audio output support! 2018-04-12 16:35:13 -07:00
background.h Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
clocks.c Turn on nvm in 3.0. 2018-04-13 16:22:28 -07:00
clocks.h Add audio output support! 2018-04-12 16:35:13 -07:00
events.c Re-enable PDMIn without ASF and using the helpers added with 2018-05-01 14:35:43 -07:00
events.h Re-enable PDMIn without ASF and using the helpers added with 2018-05-01 14:35:43 -07:00
fatfs_port.c Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
flash_api.c atmel-samd: More USB polish 2017-10-30 18:29:20 -07:00
flash_api.h atmel-samd: More USB polish 2017-10-30 18:29:20 -07:00
i2s.c Re-enable PDMIn without ASF and using the helpers added with 2018-05-01 14:35:43 -07:00
i2s.h Re-enable PDMIn without ASF and using the helpers added with 2018-05-01 14:35:43 -07:00
internal_flash.c Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
internal_flash.h Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
mpconfigport.h atmel-samd: Add rtc module support 2018-04-16 13:15:08 +02:00
mpconfigport.mk atmel-samd: Enable longints for M4 builds. 2017-10-31 15:46:42 -07:00
mphalport.c Handle bad power on reset. 2018-05-03 23:43:02 -04:00
mphalport.h Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
peripherals.c peripherals.c should include peripherals.h 2018-05-02 13:50:34 -04:00
peripherals.h Implement microcontroller.cpu.temperature on '21 and '51. 2018-05-01 21:35:55 -04:00
pins.h Implement busio.I2c. 2017-11-07 09:59:54 -08:00
qstrdefsport.h Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
reset.c merge from 2.2.0 + fix up board defs 2018-01-02 21:25:41 -05:00
reset.h atmel-samd: reset: reset() was always entering bootloader mode 2018-04-05 08:16:53 -05:00
samd21_peripherals.c fix minor comment typos 2018-05-01 22:04:11 -04:00
samd21_peripherals.h Implement microcontroller.cpu.temperature on '21 and '51. 2018-05-01 21:35:55 -04:00
samd21_pins.c Remove SERCOM pointers from pin data structure because index is 2018-03-14 11:14:32 -07:00
samd21_pins.h Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge 2017-10-24 22:31:16 -07:00
samd51_peripherals.c fix minor comment typos 2018-05-01 22:04:11 -04:00
samd51_peripherals.h Implement microcontroller.cpu.temperature on '21 and '51. 2018-05-01 21:35:55 -04:00
samd51_pins.c Remove SERCOM pointers from pin data structure because index is 2018-03-14 11:14:32 -07:00
samd51_pins.h Implement busio.I2c. 2017-11-07 09:59:54 -08:00
shared_dma.c Fix 8 bit recordings on CPX. 2018-05-02 15:15:25 -07:00
shared_dma.h Add audio output support! 2018-04-12 16:35:13 -07:00
tick.c cleanup in tick.c 2018-04-20 15:23:03 -04:00
tick.h atmel-samd: Add samd21 neopixel support. 2017-10-31 22:38:09 -07:00
timers.c Add audio output support! 2018-04-12 16:35:13 -07:00
timers.h Add audio output support! 2018-04-12 16:35:13 -07:00
usb.c Merge pull request #628 from sommersoft/super_status 2018-04-08 22:06:09 -07:00
usb.h Implement busio.I2c. 2017-11-07 09:59:54 -08:00
usb_mass_storage.c Check usb_busy up front in usb background function. 2018-03-14 10:32:41 -07:00
usb_mass_storage.h atmel-samd: More USB polish 2017-10-30 18:29:20 -07:00

README.rst

SAMD21x18
=========

This port brings MicroPython to SAMD21x18 based development boards under the name
CircuitPython. Supported boards include the Adafruit CircuitPlayground Express,
Adafruit Feather M0 Express, Adafruit Metro M0 Express, Arduino Zero, Adafruit
Feather M0 Basic and Adafruit M0 Bluefruit LE.

Pinout
------

All of the boards share the same core pin functionality but call pins by
different names. The table below matches the pin order in
`the datasheet <http://ww1.microchip.com/downloads/en/DeviceDoc/40001882A.pdf>`_
and omits the pins only available on the largest package because all supported
boards use smaller version.

=====================  ===============  ===========================  ======================  ================  ==================  =========================  ================  ================
`microcontroller.pin`  `board`
---------------------  -------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Datasheet              arduino_zero     circuitplayground_express    feather_m0_adalogger    feather_m0_basic  feather_m0_express  gemma_m0                   metro_m0_express  trinket_m0
=====================  ===============  ===========================  ======================  ================  ==================  =========================  ================  ================
PA00                                    ``ACCELEROMETER_SDA``                                                                      ``APA102_MOSI``                              ``APA102_MOSI``
PA01                                    ``ACCELEROMETER_SCL``                                                                      ``APA102_SCK``                               ``APA102_SCK``
PA02                   ``A0``           ``A0`` / ``SPEAKER``         ``A0``                  ``A0``            ``A0``              ``A0`` / ``D1``            ``A0``            ``D1`` / ``A0``
PA03
PB08                   ``A1``           ``A7`` / ``TX``              ``A1``                  ``A1``            ``A1``                                         ``A1``
PB09                   ``A2``           ``A6`` / ``RX``              ``A2``                  ``A2``            ``A2``                                         ``A2``
PA04                   ``A3``           ``IR_PROXIMITY``             ``A3``                  ``A3``            ``A3``              ``D0`` / ``TX`` / ``SDA``  ``A3``
PA05                   ``A4``           ``A1``                       ``A4``                  ``A4``            ``A4``              ``D2`` / ``RX`` / ``SCL``  ``A4``
PA06                   ``D8``           ``A2``                       ``D8`` / ``GREEN_LED``                    ``NEOPIXEL``                                   ``D8``            ``D4`` / ``TX``
PA07                   ``D9``           ``A3``                       ``D9``                  ``D9``            ``D9``                                         ``D9``            ``D3`` / ``RX``
PA08                   ``D4``           ``MICROPHONE_DO``            ``D4`` / ``SD_CS``                                                                       ``D4``            ``D0`` / ``SDA``
PA09                   ``D3``           ``TEMPERATURE`` / ``A9``                                                                                              ``D3``            ``D2`` / ``SCL``
PA10                   ``D1`` / ``TX``  ``MICROPHONE_SCK``           ``D1`` / ``TX``         ``D1`` / ``TX``   ``D1`` / ``TX``                                ``D1`` / ``TX``   ``D13``
PA11                   ``D0`` / ``RX``  ``LIGHT`` / ``A8``           ``D0`` / ``RX``         ``D0`` / ``RX``   ``D0`` / ``RX``                                ``D0`` / ``RX``
PB10                   ``MOSI``                                      ``MOSI``                ``MOSI``          ``MOSI``                                       ``MOSI``
PB11                   ``SCK``                                       ``SCK``                 ``SCK``           ``SCK``                                        ``SCK``
PA12                   ``MISO``         ``REMOTEIN`` / ``IR_RX``     ``MISO``                ``MISO``          ``MISO``                                       ``MISO``
PA13                                    ``ACCELEROMETER_INTERRUPT``                                                                                           ``FLASH_CS``
PA14                   ``D2``           ``BUTTON_B`` / ``D5``                                                                                                 ``D2``
PA15                   ``D5``           ``SLIDE_SWITCH`` / ``D7``    ``D5``                  ``D5``            ``D5``                                         ``D5``
PA16                   ``D11``          ``MISO``                     ``D11``                 ``D11``           ``D11``                                        ``D11``
PA17                   ``D13``          ``D13``                      ``D13`` / ``RED_LED``   ``D13``           ``D13``                                        ``D13``
PA18                   ``D10``                                       ``D10``                 ``D10``           ``D10``                                        ``D10``
PA19                   ``D12``                                       ``D12``                 ``D12``           ``D12``                                        ``D12``
PA20                   ``D6``           ``MOSI``                     ``D6``                  ``D6``            ``D6``                                         ``D6``
PA21                   ``D7``           ``SCK``                      ``D7`` / ``SD_CD``                                                                       ``D7``
PA22                   ``SDA``                                       ``SDA``                 ``SDA``           ``SDA``                                        ``SDA``
PA23                   ``SCL``          ``REMOTEOUT`` / ``IR_TX``    ``SCL``                 ``SCL``           ``SCL``             ``L`` / ``D13``            ``SCL``
PA24
PA25
PB22                                    ``FLASH_CS``
PB23                                    ``NEOPIXEL`` / ``D8``
PA27
PA28                                    ``BUTTON_A`` / ``D4``
PA29
PA30                                    ``SPEAKER_ENABLE``                                                                                                    ``NEOPIXEL``
PA31
PB02                   ``A5``           ``A5`` / ``SDA``             ``A5``                  ``A5``            ``A5``                                         ``A5``
PB03                                    ``A4`` / ``SCL``
=====================  ===============  ===========================  ======================  ================  ==================  =========================  ================  ================

Here is a table about which pins can do what in CircuitPython terms. However,
just because something is listed, doesn't mean it will always work. Existing use
of other pins and functionality will impact your ability to use a pin for your
desired purpose. For example, only certain combinations of SPI pins will work
because they use shared hardware internally.

=====================  ========  =========  =========  =======  =======  =======  =========  =========  =======  ==========  ==========  =========  =========  =========  ============  =======  =======  =========
`microcontroller.pin`  `analogio`           `audioio`  `bitbangio`                `busio`                                                                                 `digitalio`   `pulseio`         `touchio`
---------------------  -------------------  ---------  -------------------------  --------------------------------------------------------------------------------------  ------------  ----------------  ---------
Datasheet              AnalogIn  AnalogOut  AudioOut   I2C      OneWire  SPI      I2C - SDA  I2C - SCL  OneWire  SPI - MISO  SPI - MOSI  SPI - SCK  UART - RX  UART - TX  DigitalInOut  PulseIn  PWMOut   TouchIn
=====================  ========  =========  =========  =======  =======  =======  =========  =========  =======  ==========  ==========  =========  =========  =========  ============  =======  =======  =========
PA00                                                   **Yes**  **Yes**  **Yes**  **Yes**               **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**
PA01                                                   **Yes**  **Yes**  **Yes**             **Yes**    **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA02                   **Yes**   **Yes**    **Yes**    **Yes**  **Yes**  **Yes**                        **Yes**                                                           **Yes**       **Yes**           **Yes**
PA03                   **Yes**                         **Yes**  **Yes**  **Yes**                        **Yes**                                                           **Yes**       **Yes**           **Yes**
PB08                   **Yes**                         **Yes**  **Yes**  **Yes**  **Yes**               **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**           **Yes**
PB09                   **Yes**                         **Yes**  **Yes**  **Yes**             **Yes**    **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**  **Yes**  **Yes**
PA04                   **Yes**                         **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**  **Yes**
PA05                   **Yes**                         **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**  **Yes**  **Yes**
PA06                   **Yes**                         **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**  **Yes**
PA07                   **Yes**                         **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**  **Yes**  **Yes**
PA08                   **Yes**                         **Yes**  **Yes**  **Yes**  **Yes**               **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA09                   **Yes**                         **Yes**  **Yes**  **Yes**             **Yes**    **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA10                   **Yes**                         **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA11                   **Yes**                         **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**     **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PB10                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PB11                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**     **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA12                                                   **Yes**  **Yes**  **Yes**  **Yes**               **Yes**  **Yes**                            **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA13                                                   **Yes**  **Yes**  **Yes**             **Yes**    **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA14                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA15                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**     **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA16                                                   **Yes**  **Yes**  **Yes**  **Yes**               **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA17                                                   **Yes**  **Yes**  **Yes**             **Yes**    **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA18                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA19                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**     **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA20                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA21                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**     **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA22                                                   **Yes**  **Yes**  **Yes**  **Yes**               **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA23                                                   **Yes**  **Yes**  **Yes**             **Yes**    **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PA24
PA25
PB22                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**
PB23                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**     **Yes**    **Yes**               **Yes**       **Yes**
PA27                                                   **Yes**  **Yes**  **Yes**                        **Yes**                                                           **Yes**       **Yes**
PA28                                                   **Yes**  **Yes**  **Yes**                        **Yes**                                                           **Yes**       **Yes**
PA29                                                   **Yes**  **Yes**  **Yes**                        **Yes**                                                           **Yes**       **Yes**
PA30                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**  **Yes**
PA31                                                   **Yes**  **Yes**  **Yes**                        **Yes**  **Yes**     **Yes**     **Yes**    **Yes**               **Yes**       **Yes**  **Yes**
PB02                   **Yes**                         **Yes**  **Yes**  **Yes**  **Yes**               **Yes**  **Yes**     **Yes**                **Yes**    **Yes**    **Yes**       **Yes**           **Yes**
PB03                   **Yes**                         **Yes**  **Yes**  **Yes**             **Yes**    **Yes**  **Yes**                 **Yes**    **Yes**               **Yes**       **Yes**           **Yes**
=====================  ========  =========  =========  =======  =======  =======  =========  =========  =======  ==========  ==========  =========  =========  =========  ============  =======  =======  =========

Setup
-----

An ARM compiler is required for the build, along with the associated binary
utilities.  On Ubuntu, these can be installed as follows:

.. code-block:: shell

    sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
    sudo apt-get install gcc-arm-embedded

On Arch Linux the compiler is available for via the package
``arm-none-eabi-gcc``.

For other systems, the `GNU Arm Embedded Toolchain <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`_
may be available in binary form.

The latest available package from team-gcc-arm-embedded is used to produce the
binaries shipped by AdaFruit.  Other compiler versions, particularly older
ones, may not work properly.  In particular, the ``gcc-arm-none-eabi`` package
in Debian Stretch is too old.

The compiler can be changed using the ``CROSS_COMPILE`` variable when invoking
``make``.

Building
--------

Before building the firmware for a given board, there are two additional steps.
These commands should be executed from the root directory of the repository
(``circuitpython/``).

1. There are various submodules that reside in different repositories. In order
   to have these submodules locally, you must pull them into your clone, using:

.. code-block:: shell

   git submodule update --init --recursive

2. 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:

.. code-block:: shell

    make -C mpy-cross


Build commands are run from the ``circuitpython/ports/atmel-samd`` directory.

To build for the Arduino Zero:

.. code-block:: shell

    make

To build for other boards you must change it by setting ``BOARD``. For example:

.. code-block:: shell

    make BOARD=feather_m0_basic

Board names are the directory names in the `boards <https://github.com/adafruit/circuitpython/tree/master/ports/atmel-samd/boards>`_ folder.

Deploying
---------

Arduino Bootloader
^^^^^^^^^^^^^^^^^^

If your board has an existing Arduino bootloader on it then you can use bossac
to flash MicroPython. First, activate the bootloader. On Adafruit Feathers you
can double click the reset button and the #13 will fade in and out. Finally,
run bossac:

    tools/bossac_osx -e -w -v -b -R build-feather_m0_basic/firmware.bin

No Bootloader via GDB
^^^^^^^^^^^^^^^^^^^^^

This method works for loading MicroPython onto the Arduino Zero via the
programming port rather than the native USB port.

Note: These instructions are tested on Mac OSX and will vary for different
platforms.

    openocd -f ~/Library/Arduino15/packages/arduino/hardware/samd/1.6.6/variants/arduino_zero/openocd_scripts/arduino_zero.cfg

In another terminal from ``micropython/atmel-samd``:

    arm-none-eabi-gdb build-arduino_zero/firmware.elf
    (gdb) tar ext :3333
    ...
    (gdb) load
    ...
    (gdb) monitor reset init
    ...
    (gdb) continue

Connecting
----------

Serial
^^^^^^

All boards are currently configured to work over USB rather than UART. To
connect to it from OSX do something like this:

    screen /dev/tty.usbmodem142422 115200

You may not see a prompt immediately because it doesn't know you connected. To
get one either hit enter to get `>>>` or do CTRL-B to get the full header.

Mass storage
^^^^^^^^^^^^

All boards will also show up as a mass storage device. Make sure to eject it
before resetting or disconnecting the board.