Creating a SAMD21 MakeCode target
This guide describes the steps to get a SAMD21 based target setup and working.
Prerequisites
Install Node (minimum version 5.7) and npm (should come with Node)
Install the PXT command line:
npm install -g pxt
Read the Creating Targets docs.
Step 1: UF2-SAMD21 Bootloader
Create a new pull request in the UF2-SAMD21 bootloader repo to add a config for the board. The README has details on how to create a configuration. You can look at the generic config to see an example.
Step 2: Create a target repo
Clone pxt-sample as the base to create your target. Be sure to run npm install
in this repo.
You can serve the sample editor by running pxt serve
in the root directory.
Step 3: Take a look at pxtarget.json
Inside your repo, you will need a pxtarget.json
file that configures the pxt editor for your target.
See the pxtarget page for documentation on this file and all of the options that are available.
Step 4: Add the common packages
pxt-common-packages is the repo where the CODAL code common to all SAMD21 targets lives.
Run npm install --save pxt-common-packages
inside the target repo (your new target built from pxt-sample) to add it to your target.
If you are developing libraries locally, you can instead clone the pxt-common-packages repo from Github and link it like so: npm link <path to cloned repo>
(be sure to add it to your package.json
if you link the package locally).
Step 5: Setting up the target’s libs folder.
The libs
folder in a target contains the libraries of code that run on the actual device.
Libraries are a combination of C++ and TypeScript (*.ts) files that define the APIs available in the block and text editors.
To set up your target’s libs
folder, do the following:
Add the pxt-common-packages “core” library
This step is used to configure the “core” library in pxt-common-packages. You can also use following steps for any other library you wish to include from pxt-common-packages.
Delete the contents of the
libs\core
in the pxt-sample repo.Create a new file named
pxt.json
containing this:{ "additionalFilePath": "../../node_modules/pxt-common-packages/libs/core" }
With the file path configured, any file that is added to this directory with the same name as a file in the pxt-common-packages core library will override that file. Using this method you can override any of the files in pxt-common-packages.
Repeat these steps for the “base” library in pxt-common-packages.
Add your board’s “main” library
Inside the
libs
folder, create a directory with the name of your board. This directory will be the main library for your board and should contain any code that does not belong in pxt-common-packages. Add apxt.json
file to this folder that depends on the “core” library created in the previous step. See the pxt.json in the pxt-adafruit circuit-playground library as an example of what this file should look like.Add a file named
config.ts
. This file is used to configure the pinout of the board. See the pxt-adafruit circuit-playground’s config.ts for an example.Add another file named
device.d.ts
. This file is used to define the components of the board that will be visible to TypeScript. See the pxt-adafruit circuit-playground’s device.d.ts for an example.Be sure to add both
device.d.ts
andconfig.ts
to thepxt.json
you added in step 1.
Add the “blocksproj” library
Inside the libs
folder, you need a blocksproj
lib.
This library contains the default, or “base”, project that is initially loaded in the editor when the user starts a new project.
The main.blocks
file contains the XML definition for the initial blocks of the project. For now, you can leave it as is.
Inside the pxt.json
of this library, add a dependency for the “main” library created in the last step.
Step 6: Add the common-sim library
For the pxt simulator to simulate functions defined in C++, equivalent TypeScript versions of the functions are necessary. The npm module for pxt-common-packages includes a “common-sim” file that defines the simulator implementations for all of its APIs. To use common-sim in your target:
Inside
sim\public\sim.manifest
add a line with the contents/sim/common-sim.js
under theCACHE
section.Inside
sim\public\simulator.html
add a script tag for/sim/common-sim.js
above the script tag for/sim/sim.js
.Inside
sim\simulator.ts
add/// <reference path="../built/common-sim.d.ts"/>
to the top of the file.Inside
sim\simulator.ts
modify theBoard
class to implement theCommonBoard
interface from common-sim.
Step 7: Next steps
At this point, you should have a basic target that can generate UF2 files. Check out these next steps to further customize your target.
Go to the theming docs for details on how to customize the look and feel of the editor.
Learn how to define blocks for your target using comment annotations.
Add documentation to your editor. Find out how to write reference and project topics in markdown.