Adding a new board

Prerequisites

Before adding a new board, make sure your chip can be found under the pac/ directory of this project, and if not, you'll want to add a new chip first.

Copy an existing board

When I go about adding a new board, I find it easiest to copy an existing board that is fairly simple, like the Gemma M0, and make my changes inside the copy. You'll also want to remove the Cargo.lock file.

$ cp -r boards/gemma_m0 boards/YOUR_BOARD_NAME
$ cd boards/YOUR_BOARD_NAME
$ rm Cargo.lock

Editing Cargo.toml

Set the name field of Cargo.toml to your board's name, the version to 0.1.0, and the author to your name and email. Under [features], replace samd21e18a with your chip name. If you're working on a samd51 board, also add samd51 = [] as a feature. This lets the hal know you have a samd51, and makes all the changes required for samd51 boards.

Editing memory.x

This file specifies how much RAM and flash your board has, and at what address in the memory map these regions exist. It also offsets the start address of flash by a certain amount, so you don't accidentally overwrite your bootloader. The Gemma M0 has 256K of flash, an 8K bootloader, and 32K of RAM. Replace these values in the file with the correct values for your board.

Editing src/lib.rs

This file is where your the pin mappings of your board are defined. Before we get to defining the pins though, once again we have to replace atsamd21e18a with our chip name. Now, when you go about defining pins, all you do is pin PIN_NAME = MCU_PIN_NAME. For example, if you have pin d0 = a4, that means your board has a pin named d0 that corresponds to the microcontroller's PA04 pin.

Editing examples/blinky_basic.rs

Change the extern crate gemma_m0 as hal; statement to match your board name. Determine whether your board uses an internal or external crystal (schematics are helpful here), and select the correct method in this line:

let mut clocks = GenericClockController::with_internal_32kosc

You may also need to update the name of the pin for your LED if it isn't on a pin named d13.

Editing README.md

Provide a description of your board and a link to your documentation or where to buy it. Also add to the main README.md to let people know your board is part of this github repo.

Adding .cargo/config (SAMD51 only)

The .cargo/config file tells cargo which architecture to compile for, and since SAMD51 is a different architecture than SAMD21, we need this file. Copy it from the Metro M4.

cp -r ../metro_m4/.cargo .

Testing

Follow the instructions in the main README of atsamd-rs/atsamd to build and flash your blinky. If it blinks, you're good to go.

Adding your board to the build system

Add your board to crates.json.

Congratulations

Woohoo! You did it. Don't forget to send us a PR so everyone can use your changes.