MakeCode: Creating Custom Boards

Over the past year I have spent a lot of time porting different libraries to the Robo HAT MM1 board developed by Robotics Masters. This has lead to discovering a lot about these libraries, how they work behind the scenes and most importantly - what to do to add new boards in the future.

This part of a series of write-ups I will be doing to help others who wish to port libraries for their boards. Many of the sources of information can be vague or difficult for outsiders to understand. I hope to ‘demystify’ and explain how to achieve a successful port for everyone.

Today, we will be looking at the MakeCode platform by Microsoft. This platform is very popular for using with the microbit and Adafruit CircuitPlayground Express. There are currently only a few different board variants - mostly produced by Adafruit and some smaller community members.

This guide will help you add your board to MakeCode so you too can enjoy the benefits that it gets. It goes deeper than the documentation so that you can use your own pin names and other cool features.

What is MakeCode?

MakeCode is similar to Scratch in that the basis of the program is that you have 'blocks' of code that can be dragged into a work space and manipulated into forming logical code. The key difference is that MakeCode has a power simulate included that shows exactly what your real life board should be doing. It supports JavaScript and Python programming languages that work with the blocks.

Microsoft describes it as: Hands-on computing education

Microsoft MakeCode brings computer science to life for all students with fun projects, immediate results and both block and text editors for learners at different levels.

Before You Begin

MakeCode makes it easy to to port your board. All you need to know is what processor model variant you are using (SAMD51, SAMD21, etc) and the rest should be straight forward.

The easiest way to approach porting your board is to look at what is a similar Adafruit board model and then start there.

Once you have all the information you need about the processor you are using, you can start to look at the software and modify it to work for your custom board.

Let's Begin!

The developers of MakeCode have their own existing documentation that is publicly available. So we will start with this and expand from there.

https://maker.makecode.com/boards/add-a-new-board

Summary:

• Install Dependencies
• Clone repository all repositories and npm install
• Bootloader
• Project Files
• SVG Image and associated files
• Pull Request

Each step will be explained in detail below.

I used Windows 10 for all these instructions, but I believe they are platform independent.

Step 1 - Environment Setup

MakeCode requests NodeJS and Node Package Manager (NPM) tools for it to run successfully.

Additionally, if you are adding or expanding the functionality you will want Docker installed as well. Without going into much detail, I will just leave the links below for you to download those programs.

Installing NodeJS

Installing Docker

These are platform independent. So they should work on both Mac, Windows and Linux.

Advanced

Installing CMake (and add to path, CMAKE_C_COMPILER)

Ninja Install (and move to CMake folder)

Visual Studio 2019 (optional)

Step 2 - Local Dev Environment Server

These instructions are very clear from the existing MakeCode documentation. I will put them here so everything is in one place and add some notes.

Start by making a folder called makecode somewhere on your computer. We will use this folder to keep all the MakeCode repositories together. Make sure you run all the below commands from the makecode folder.

MakeCode uses 3 main repositories for enabling the application to run.

Ensure you follow these instructions carefully and run each command sequentially.

pxt repository

git clone https://github.com/microsoft/pxt
cd pxt
npm install
npm run build
cd ..

pxt-common-packages repository

git clone https://github.com/microsoft/pxt-common-packages
cd pxt-common-packages
npm install
cd ..

pxt-maker repository

git clone https://github.com/microsoft/pxt-maker
cd pxt-maker
npm install -g pxt
npm install

Link repositories together (add sudo for Mac/Linux)

rm -Rf node_modules/pxt-core
rm -Rf node_modules/pxt-common-packages
pxt link ../pxt
pxt link ../pxt-common-packages

At the end of running all the above commands you should end up with a folder structure like so:

makecode/
  - pxt/
  - pxt-common-packages/
  - pxt-maker/

Test Deployment

At this point, you can run MakeCode and see all it's existing features. You will want to make sure it builds properly at this stage as it is still under development and can have issues. The pxt command allows you to do many things relating to MakeCode. It is always run from the root of the pxt-maker folder. We will just ask it to serve the web server for now.

cd makecode/pxt-maker
pxt serve

The first time you run pxt serve it takes a long time to build. I have noticed it has two stages of building. So you may have to wait up to 10 minutes for the initial build to complete.

If you can load up MakeCode without issues, then you can continue to adding your own custom board.

Step 3 - Custom Board Bootloader

MakeCode is dependant on your board supporting the UF2 Bootloader standard. You need to make sure that you have created a UF2 Bootloader for your custom board before continuing.

I already did a very detailed write up for UF2 Bootloader - Creating Custom Boards. Quickly jump over there and get that done now!

Step 4 - Add a new board

The absolute best way for adding a new board is to just copy and existing one and modify only the essentials to make your new board run.

All of Adafruit's Feather line of boards are included in MakeCode already. So you just need to pick the one that is the closest match to your board (same processor). Below are some examples.

• Adafruit Feather M0 - SAMD21G18A
• Adafruit ItsyBitsy M4 - SAMD51G19A
• Adafruit Feather M4 - SAMD51J19A

All of the work we do will take place in the pxt-maker repository.

Let's start by copying an existing board (adafruit-itsybitsy-m4-express) and create a new board for the Robo HAT MM1 M4 (robohatmm1-m4). For this whole tutorial, replace robohatmm1-m4 with your custom board name.

cd makecode/pxt-maker
cd libs
cp -r adafruit-itsybitsy-m4-express/ robohatmm1-m4/

You can do this with Explorer or Finder GUIs if you prefer.

Take a look in the new folder (robohatmm1-m4) we just created to get familiar with the different files and structure.

_locales/
built/
board.json
board.svg
boardhd.svg
config.ts
device.d.ts
ns.ts
pxt.json
README.md

Folders

There are two folders. These can be safely ignored as all the files inside them are automatically generated.

Files

board.json - (generated & modified) relates to boardhd.svg and is generated in a later step. It holds the positions of important features on the SVG file.

board.svg - (generated) relates to boardhd.svg. It is a striped down version of boardhd.svg.

boardhd.svg - (created by you) your custom SVG file that has an image of your custom board with particular dimensions and specifications. It is the core part of MakeCode working successfully with your board.

config.ts - (generated & modified) closely related with your board's schematic. It contains the information that links the pins labelled on the SVG to your board's processor.

device.d.ts - (generated & modified) related to your board's schematic. Contains information about the types of functions allowed to be called with different pins.

ns.ts - (generated & modified)

pxt.json - (modified) the metadata information used to create the simulator and other parts of MakeCode run with your board. More information later on what you should customise in this file.

README.md - (modified) not much goes on here. Just put your board name in it.

Step 5 - Modifying Files

The MakeCode instructions are very straight forward on which files need to be updated and changed - they have also been improved recently to make it even easier. All of these steps are performed in the pxt-maker/libs/<your_custom_board> directory unless otherwise stated.

Let's start with the easiest part. Create README.md file in your custom board directory.

# Robotics Masters Robo HAT MM1 M4

That's all you need in it.

Next, update the following fields in pxt.json

• name
• description
• compileServiceVariant (if you did not pick the right processor)

In this file you can also edit the features for your board. You may have an accelerator or neopixel lights on the board that you want to support. I am currently working on a list of all the available features and will post them somewhere at the end of this guide.

Update pxtarget.json to include your new board. You will need to go to the root of the repository and update the bundled-dirs array. Add the name of the folder for your custom board to the end of this array. This tells pxt to compile in your board.

Next, go and create a file for your board /docs/boards/<custom_board_name>.md. You can copy an existing board's file and just rename it. This file is not all that important.

After this you need to put an image of your board into: /docs/static/libs/<custom_board_name>.jpg. Make sure that the dimensions of the file are no larger than 500 px x 500 px. The image does not need to be square.

I discovered this by mistake. If you do not put an image in this folder, your board does not list correctly with all the other boards.

Step 6 - SVG File and Board Designer

The next steps all relate to the SVG file that MakeCode depends on to correctly work with your board.

There are some strict rules about how the file must be created. It is highly recommended that you use InkScape on Windows. Other rules include the following:

SVG Requirements

• All Pin Headers must be 15px by 15px
• The name of each LED on the board must be LED0, LED1,..., etc
• The name of the reset button must be RESETBTN
• For Serial, must have TX pin labelled as "TX" to work

SVG Recommendations

• All Pins must be named how it is labelled on the board (NOTE: This can be changed later).
• Additional Pins can be named JACK_
• Name touch pins as "TOUCH"
• Remove extra components that do not have any functionality
• If using NEOPIXELs, name the NEOPIXEL LED as NEOPIXEL
• Use the existing pin names (do not create own names)
• Recommended dimensions are 500px x 500px (square, if possible)

If you follow all the above requirements and recommendations it makes the next steps easier.

Save the SVG file in the libs/<your_custom_board> folder as boardhd.svg.

One of the steps is to minimise the SVG file by running the following command at the pxt-maker folder level.

svgo --config=svgo.yml libs/YOUR_BOARD_NAME/boardhd.svg -o libs/YOUR_BOARD_NAME/board.svg

If this command does not work, you can run it for all boards (it just takes longer).

npm run svgo

Once you have create your minified SVG (board.svg) and you are happy with it, you can put it into the Board Designer. Open up the SVG in NotePad or similar text editor and copy all the text into the text box on the Board Designer.

Hopefully below the text box will appear your SVG file with yellow highlights around the pins that it has automatically detected.

If it has found all your pins, that means you should have very few issues. Otherwise I would recommend going back and checking that you followed all the SVG requirements and recommendations above.

The Board Designer generates two files that MakeCode needs. It is not perfect. You will probably need to check the file that it has created and edit it accordingly.

Step 6B - board.json

board.json maps where all the pins on your SVG appear. It has x and y coordinates so that the MakeCode editor can interact with your simulated board.

The gpioPinMap array (about halfway down the file) will need to be updated so that it contains the correct names for all the parts for your board. Take a look at the Robo HAT MM1's initially generated file vs the final product.

Cleaning up this array makes it easier to find issues later on. It also looks much better. The cleaning strategy is:

• Remove duplicate names
• Remove un-needed pins (maybe capacitors, resistors)
• Rename to a standard for GND, 5V and 3V pins
• Rename data pins to be the same they appear in SVG
• Sort all the pins alphabetically

Do the same for the groundPins, threeVoltPins, fiveVoltPins and other arrays below.

The end result is a nice, clean file. Save it into your board directory with the SVG.

Step 6C - config.ts

The next file to clean up is the config.ts file. This is created on the board designer below board.json.

I personally have had little to 0% using this tool. My recommendation is to just make this file yourself from scratch. The information you need is the following:

• Pin Names
• Pin Hardware Numbers (e.g. PA12)
• Pin Aliases (if a pin has more than one function)

Check out the Robo HAT MM1 HAT as an example. It is pretty self explanatory.

NOTE: You must put in a PIN_TX if you want serial to work. This was one of the issues I had adding my first board to MakeCode.

Step 6D - device.d.ts

There is one last file that needs to be modified before you can use your board with MakeCode. The device.d.ts file sets the the functionality of each pin. If you want a SERVO pin, you will need to set it as PWM. If you want an ANALOG pin you will want to set it as DigitalInOut.

Check out the below example and then the recommendations for how to setup this file.

Recommendations:

• Declare all pins in the pins array at the top
• Set all Communication pins as DigitalInOutPin
• Set all PWM pins as PwmPin
• Set all LEDs as PwmOnlyPin
• Make sure that the alias names in this file are set the same as each other.
• Declare all buttons in the input array at the bottom
• TIP: All the names in this file will appear in MakeCode GUI.

Running MakeCode with Custom Board (Workflows)

You should now have all the following files in your custom-board folder.

You should now be able to run MakeCode with your custom board showing up in the GUI. A word of warning - your board may not run perfectly the first time and it might take some fiddling around before you have a perfect board.

Below are some of the workflows that I followed to ensure that MakeCode ran correctly. Make sure you are running these in the pxt-maker folder. You should be ok with using just the first two.

Normal Server

pxt serve

Clean Build

pxt clean
pxt serve

CODAL Local Build (part 2 of guide, later date)

export NO_DOCKER=1
pxt build --local --force

Concluding Notes

If you get to this stage you should have at least a working board. This concludes creating custom MakeCode boards. It was a bit more difficult than I anticipated but fun nonetheless to now have it completed.

Microsoft supports adding or merging in your changes to MakeCode on GitHub. Be sure that you do a Pull Request and get your board added.

Special Mentions to the Microsoft Team who maintain MakeCode:

• Peli de Halleux (pelikhan)

Please feel free to leave any comments down below if you get into trouble.

Thank you for reading along!

There will be a part 2 later on with how to build for CODAL and update C++ files for adding cool new sensors in the future! Stay posted for that one.