Initial Steps for Adding Your Board

To demonstrate, this guide will walk through adding a board similar to the Trinket M0 called PyRuler.

Duplicate a Current Board Directory

Take a look at the existing boards available for CircuitPython and choose one that is close to yours so you have something to start with to modify.

The most important things to match are:

• Which version of the microcontroller are you using? You'll want to match as closely as possible to ensure RAM, size, etc are the same. You can do this by verifying that the full name of the chip, e.g. ATSAMD51J19, matches the board you're copying from.
• Does your board have external SPI flash? If so, choose a board to start with that also has external SPI flash, such as the Adafruit Feather M4 Express. Try to find a board that has the same SPI flash chip as you are using. See SPI Flash Configuration below for more details.
• Does your board have a crystal, or lack a crystal that is usually included? If so, look at other similar boards in the same port. This is of particular interest in the atmel-samd and nrf ports.

Find the board directory you're choosing to start with in /ports/<your-port>/boards. In this example, PyRuler is similar to the Trinket M0, in the atmel-samd port.

Board Files

Each board directory contains four files. These files currently contain information for the board you chose to duplicate. You will need to go over each file and apply the necessary changes to make the files fit your board. The files are:

Verify the REPL is Working

The first thing you want to do is verify that you can build for your board by making the most basic changes possible, building CircuitPython, loading it on your board, and ensuring that you can get to the REPL. Other things like pin names will be incorrect, but this will verify that the build process works and that you can load the firmware.

These changes include:

• Update the board name to match your board name in mpconfigboard.h
• Verify your chip variant is correct in mpconfigboard.h and mpconfigboard.mk
• Verify that the SPI flash configuration matches in mpconfigboard.h and mpconfigboard.mk
• Verify the crystal configuration matches in mpconfigboard.h

If you've chosen a board that matches your configuration, the last three things on this list should already match. If not, be sure to update them to match.

Board Name

Updating the board name to match your board name means when you load the REPL, your board name will show up in the initial info line. It's a simple way to know that your changes have been included in your new build. To update the board name, open mpconfigboard.h. Change the string in the BOARD_NAME line to match the full name of your board. The name should include both the manufacturer and the board name.

#define MICROPY_HW_BOARD_NAME "Adafruit PyRuler"

#define MICROPY_HW_BOARD_NAME "Adafruit PyRuler"

Chip Variant

If you've chosen a set of board files to modify from a board that uses the exact same chip as yours, then no changes are necessary. However, it's always worth verifying that the chip variant matches.

There are two places where the chip variant on the board is identified: mpconfigboard.h and mpconfigboard.mk. Start with mpconfigboard.h as you should already have it up.

In mpconfigboard.h, verify that the string in the MCU_NAME line matches your chip. It can be the full name of the chip - you'll notice that in the PyRuler example, it does not include the last letter of the chip name. This MCU name is used in various strings in CircuitPython, such as the string in the REPL that identifies which board you're using.

#define MICROPY_HW_MCU_NAME "samd21e18"

#define MICROPY_HW_MCU_NAME "samd21e18"

In mpconfigboard.mk, verify that the CHIP_VARIANT and CHIP_FAMILY match your chip. These affect the compilation of CircuitPython.

The CHIP_VARIANT should be the full name of the chip, e.g. SAMD21E18A.

The CHIP_FAMILY should be the beginning of the chip name, including the product family and the product series, e.g. samd21.

CHIP_VARIANT = SAMD21E18A
CHIP_FAMILY = samd21

CHIP_VARIANT = SAMD21E18A
CHIP_FAMILY = samd21

SPI Flash Configuration

You will want to ensure that you've started with an existing Adafruit board that has the same SPI flash configuration. The currently supported chips are listed in supervisor/shared/external_flash/devices.h. There is a lot involved in setting up a new SPI flash chip that will not be covered in this guide at this time. We only guarantee support for the flash chips used on Adafruit boards. This is not to say that other flash chips will not work, it's simply to say we don't guarantee that they will.

Crystal Configuration

For atmel-samd, this is as simple as whether or not your board has a crystal or not. If your board has a crystal, find an existing board that also has a crystal, as suggested above. Include #define BOARD_HAS_CRYSTAL 1 in your mpconfigboard.h file. If you don't have a crystal, we'll try to sync to the USB 1KHz clock pulses to calibrate the crystal, which save space and component cost, but is less precise when USB isn't connected.

For other ports, such as nrf, a board may have a crystal included inside the on-board module. An nrf board may have one or two crystals, and the flags for mpconfigboard.h will differ from atmel-samd. Again, look at similar boards. For some ports, a crystal is always required, and these flags are not used.