36 changes: 27 additions & 9 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,33 @@
# Contributing
Please note that this project is released with a
[Contributor Code of Conduct](https://github.com/adafruit/circuitpython/blob/master/CODE_OF_CONDUCT.md).
By participating in this project you agree to abide by its terms. Participation
covers any forum used to converse about CircuitPython including unofficial and official spaces. Failure to do
so will result in corrective actions such as time out or ban from the project.

Please note that this project is released with a Contributor Code of
Conduct. By participating in this project you agree to abide by its terms.
## Developer contact
[@tannewt](https://github.com/tannewt) is the main developer of CircuitPython
and is sponsored by [Adafruit Industries LLC](https://adafruit.com). He is
reachable on [Discord](https://adafru.it/discord) as tannewt and
[Gitter](gitter.im/adafruit/circuitpython) as tannewt during US West Coast
working hours. He also checks GitHub issues and the [Adafruit support forum](https://forums.adafruit.com/viewforum.php?f=60).

https://github.com/adafruit/micropython/blob/master/CODE_OF_CONDUCT.md
## Licensing
By contributing to this repository you are certifying that you have all necessary
permissions to license the code under an MIT License. You still retain the
copyright but are granting many permissions under the MIT License.

When reporting an issue and especially submitting a pull request, please
make sure that you are acquainted with Contributor Guidelines:
If you have an employment contract with your employer please make sure that they
don't automatically own your work product. Make sure to get any necessary approvals
before contributing. Another term for this contribution off-hours is moonlighting.

https://github.com/micropython/micropython/wiki/ContributorGuidelines
## Code guidelines
We aim to keep our code and commit style compatible with MicroPython upstream.
Please review their
[code conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md) to do so.
Familiarity with their [design philosophy](https://github.com/micropython/micropython/wiki/ContributorGuidelines)
is also useful though not always applicable to CircuitPython.

and Code Conventions:

https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md
Furthermore, CircuitPython has a
[design guide](https://circuitpython.readthedocs.io/en/latest/docs/design_guide.html)
that covers a variety of different topics. Please read it as well.
121 changes: 117 additions & 4 deletions atmel-samd/README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,131 @@
SAMD21x18
=========

This port brings MicroPython to SAMD21x18 based development boards including the
Arduino Zero, Adafruit Feather M0 Basic and Adafruit M0 Bluefruit LE.
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`` ``NEOPIXEL`` ``D8`` ``D4`` / ``TX``
PA07 ``D9`` ``A3`` ``D9`` ``D9`` ``D9`` ``D9`` ``D3`` / ``RX``
PA08 ``D4`` ``MICROPHONE_DO`` ``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`` ``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``
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**
===================== ======== ========= ========= ======= ======= ======= ========= ========= ======= ========== ========== ========= ========= ========= ============ ======= ======= =========

Building
--------

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/atmel-samd/boards>`_ folder.
Expand Down Expand Up @@ -41,7 +154,7 @@ 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`:
In another terminal from ``micropython/atmel-samd``:

arm-none-eabi-gdb build-arduino_zero/firmware.elf
(gdb) tar ext :3333
Expand Down Expand Up @@ -70,7 +183,7 @@ Mass storage
^^^^^^^^^^^^

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

Port Specific modules
---------------------
Expand Down
Loading