Advanced: Creating Your Own Port

If you want to port CircuitPython to your own Microchip ATSAMD21 board, there are several steps you will need to take.

This is for advanced users only! You will need access to a Linux or Unix-based operating system and know your way around a command line. The details for building the projects are located in the repositories and not covered here.

1. Create a UF2 Port

Before you can get CircuitPython onto your board, you will need to create a UF2 bootloader unique to your board.

Clone the Adafruit uf2-samdx1 repository. If you have already cloned the repository, you will need to update your forked copy with the following commands. First, check to see if you have the upstream repository added with:

git remote -v

If you do not see upstream locations, add the Adafruit repository:

git remote add upstream https://github.com/adafruit/uf2-samdx1.git

Update your repository with any new additions to the upstream repository:

git fetch upstream

git checkout master

git rebase upstream/master

Create a new folder in boards/ with your particular board name. Create the following files in your new folder:

  • board.mk
  • board_config.h

Use other board files as examples for how to fill out your files.

You will need to reference the schematic for your board to find which SAMD21 pin maps to the onboard LED (or other important peripherals for UF2). Additionally, you will need to assign a unique and legitimate USB VID and PID to your board for the UF2 bootloader drive.

Look at the README in the uf2-samdx1 repository for instructions on how to build the UF2 files for your board (including the Arduino .ino program that will automatically upload the bootloader).

2. Create a CircuitPython Port

Clone the Adafruit CircuitPython repository. If you have already cloned the repository, you will need to update your forked copy with the following commands. First, check to see if you have the upstream repository added with:

git remote -v

If you do not see upstream locations, add the Adafruit repository:

git remote add upstream https://github.com/adafruit/circuitpython.git

Update your repository with any new additions to the upstream repository:

git fetch upstream

git checkout master

git rebase upstream/master

You will then need to synchronize the submodules in the repository:

git submodule sync

git submodule update --init --recursive

Create a new folder in ports/atmel-samd/boards with your board name. Create the following files in your new folder:

  • board.c
  • mpconfigboard.h
  • mpconfigboard.mk
  • pins.c

Refer to other board files in the atmel-samd/boards folder as examples for what should go in each of those files. You will need to look at the schematic for your board to see which pins map to which headers and peripherals.

Once again, you will need a unique and legitimate USB VID and PID for the CIRCUITPY drive (assigned in mpconfigboard.mk). The PID (and possibly the VID) should be different from the value used for UF2.

Add your board's name to the TRAVIS_BOARDS list in .travis.yml (found in the top level directory of the repository). This will tell Travis CI to automatically build CircuitPython with support for your board.

To build CircuitPython for your board, follow the instructions in the Building CircuitPython tutorial.

3. Test Your Board

Use the modules found in the Adafruit_CircuitPython_BoardTest repository to test the various pins and features of your board. Note that you will need some hardware (e.g. LEDs, resistors, EEPROM) for the tests. Refer to the README in the repository for more detailed instructions.

4. Create Pull Requests

Feel free to fork any of the repositories, make your changes, and submit a pull request. We recommend reading Contribute to CircuitPython with Git and GitHub to get a better understanding of how to contribute to the CircuitPython project. We would love to have your board port as part of CircuitPython!

5. Update Mu (Optional)

The Mu editor is quickly becoming a fan favorite for writing CircuitPython programs. If you would like to have your board supported in Mu, you will need to fork the Mu repository, make a few changes, and submit a pull request.

The documentation for building Mu can be found here: https://mu.readthedocs.io/en/latest/setup.html. However, I've outlined a brief overview for modifying and building Mu below.

First, fork the Mu repository to your own GitHub account. Next, clone it on your computer:

git clone https://github.com/[YOUR GITHUB USERNAME]/mu

Install the necessary dependencies (these were tested on Ubuntu 16.04):

sudo apt install libffi6 libffi-dev libssl-dev

sudo pip3 install virtualenv

Create a virtual environment:

virtualenv -p /usr/bin/python3 --system-site-packages ~/mu-venv

Activate the virtual environment:

source ~/mu-venv/bin/activate

In the Mu repository directory, install necessary packages:

cd mu

pip install -r requirements.txt

pip install --editable .

Add the USB VID/PID of your board to mu/modes/adafruit.py.

Build and run:

make run

Check that you can communicate with the new boards from Mu's serial terminal. If so, commit your work and submit a pull request!

 

This guide was first published on Dec 14, 2018. It was last updated on Dec 14, 2018. This page (Advanced: Creating Your Own Port) was last updated on Jun 25, 2019.