MakeCode Maker
Created by Peli de Halleux

https://learn.adafruit.com/makecode-maker

Last updated on 2024-06-03 02:31:34 PM EDT©Adafruit Industries

Page 1 of 15

Table of Contents
What is MakeCode Maker?

3Editing Blocks

5• Blinky!

Editing JavaScript6• Blocks to JavaScript

Downloading and Flashing

7• Step 1: Connect your board via USB• Step 2: Test your code in the simulator• Step 3: Download and flash your code

Saving and Sharing

10• Extracting your code from the board• Sharing

Custom Extensions11• Account setup• Commit and push
• Conflicts• Testing your package©Adafruit Industries

Page 2 of 15

What is MakeCode Maker?

MakeCode Maker, https://maker.makecode.com, is a web-based code editor forphysical computing. It provides a block editor, similar to Scratch or Code.org, and alsoa JavaScript editor for more advanced users.
Some of the key features of MakeCode are:• web based editor: nothing to install• cross platform: works in most modern browsers from tiny phone to giant touch
screens• compilation in the browser: the compiler runs in your browser, it's fast andworks offline• blocks + JavaScript: drag and drop blocks or type JavaScript, MakeCode let's
you go back and forth between the two.
• works offline: once you've loaded the editor, it stays cached in your browser.
• event based runtime: easily respond to button clicks, shake gestures and more

How is it related to makecode.adafruit.com ?
makecode.adafruit.com (https://adafru.it/wmd) and maker.makecode.com (https://adafru.it/C9N) are editors built using the MakeCode (https://adafru.it/Bhz) project.
In both editors, one can use drag-and-drop blocks or JavaScript to program microcontrollers.
• makecode.adafruit.com (https://adafru.it/wmd) specifically applies to
the Adafruit Circuit Playground Express only
• maker.makecode.com (https://adafru.it/C9N) aims at supporting the Adafruit
Express boards (and more boards from different manufacturers), with anemphasis on breadboarding support.

©Adafruit Industries

Page 3 of 15

Is it open source?
Yes, Maker is open source under MIT at https://github.com/Microsoft/pxtmaker (https://adafru.it/ND5).
Adafruit METRO M0 Express - designedfor CircuitPython
Metro is our series of microcontroller
boards for use with the Arduino IDE. This
new Metro M0 Express board looks awhole lot like our
https://www.adafruit.com/product/3505

Adafruit Feather M0 Express
At the Feather M0's heart is an
ATSAMD21G18 ARM Cortex M0+
processor, clocked at 48 MHz and at 3.3V
logic, the same one used in the newhttps://www.adafruit.com/product/3403

Adafruit GEMMA M0 - Miniature wearable
electronic platform
The Adafruit Gemma M0 is a super small
microcontroller board, with just enoughbuilt-in to create many simple projects. It
may look small and cute: round, about
the...
https://www.adafruit.com/product/3501©Adafruit Industries

Page 4 of 15

Adafruit Trinket M0 - for use withCircuitPython & Arduino IDE
The Adafruit Trinket M0 may be small, but
do not be fooled by its size! It's a tiny
microcontroller board, built around theAtmel ATSAMD21, a little chip with a lot...
https://www.adafruit.com/product/3500

Editing Blocks
The block editor is the easiest way to get started with MakeCode Maker. You can dragand drop blocks from the category list. Each time you make a change to the blocks,
the simulator will automatically restart and run the code. You can test your program in
the browser! The simulator will also generate the wiring for your breadboard forsimple programs.

On the maker home screen, click on "New Project", then select which board you
want to use (you can change board later too).

Blinky!
The animation above shows to use the blocks to create a program that blinks an LED.

©Adafruit Industries

Page 5 of 15

Creating a blink effect is done by setting the pin HIGH, pause for a little, then set thepin LOW, pause for a little, then repeat forever.
• forever runs blocks in a loop with a 20ms pause in between (it is similar toArduino loop).
• digital write pin sets the pin to high or low• pause blocks the current thread for 100ms. If other events or forever loops are
running, they have the opporunity to run in parallel.

Editing JavaScript
MakeCode allows you to author your programs in a flavor of JavaScript optimized for
micro-controllers. The code editor comes with error highlighting, auto-completion andother goodies. It is the same code editor that powers Visual Studio Code.

©Adafruit Industries

Page 6 of 15

Blocks to JavaScript
Click on the "Blocks / JavaScript" toggle on top of the editor to enter the JavaScript
mode. Your blocks will automatically be converted to JavaScript.

Downloading and Flashing
Getting your code into your device is very easy with MakeCode. You do not need toinstall any software on your machine and the process takes two steps:• Step 1: Connect your board via USB• Step 2: Compile and Download the .uf2 file into your board drive
We are going to go through these two steps in detail.
©Adafruit Industries

Page 7 of 15

Step 1: Connect your board via USB
Connect your board to your computer via a USB cable. You should see a MAKECODEdrive appear in your file explorer/finder. If your board is in bootloader mode, you willsee drive names like METROBOOT or GEMMABOOT. We will call thoseboardnameBOOT.
If it is your first time running MakeCode or if you have previously installed
Arduino or CircuitPython, you may need to double press the reset button to getyour board into bootloader mode.

Step 2: Test your code in the simulator
Let's first verify that our code compiles properly in MakeCode.
MakeCode has a built-in simulator that re-loads and re-runs code when restarted. Thisis an easy way to both ensure that our code compiles and simulate it before moving it
onto the board. The refresh button re-loads the simulator with your latest version ofblock code.

©Adafruit Industries

Page 8 of 15

If you receive a "we could not run this project" error, please check over yourcode for errors.

Step 3: Download and flash your code
If your board is working in the simulator, it's time to download it to your actual board!
Click the Download button. It will generate a .uf2 file and download it to yourcomputer. UF2 (https://adafru.it/vPE) is a file format designed by Microsoft to flash
microcontrollers over USB.

General Steps to copy over your program (not specific to any Operatingsystem)* Ensure your board is connected via USB.
* Find the .uf2 file generated by MakeCode in your file explorer. Copy it to theMAKECODE or boardnameBOOT volume.
©Adafruit Industries

Page 9 of 15* The status LED on the board will blink while the file is transferring. Once it's donetransferring your file, the board will automatically reset and start running your code
(just like in the simulator!)
On a Mac, you can safely ignore the "Disk Not Ejected Properly" notification that
may appear after copying your .uf2 file.

Saving and Sharing
Extracting your code from the board
The .uf2 file you created by clicking on the Compile button in MakeCode also
contains the source code of your program!
You can open this file in MakeCode by dragging and dropping it into the browser toedit it.
You can also find the current .uf2 file running on the MAKECODE or boardnameBOOTdrive.

Sharing
You can share your code by clicking on the share button. After confirmation,
MakeCode will create a short unique URL for your code. Anyone with that URL will beable to reload the code.
These URLs can also be used to embed the editor your blog or web pages! Just copy
paste the URL in your text editor and (if it supports oEmbed) it will automatically load
it in your page.

©Adafruit Industries

Page 10 of 15Custom Extensions
MakeCode allows to package and share code as Extensions. Extensions are stored
as GitHub repositories and can be edited directly from the MakeCode editor.

Account setup
First, you need a GitHub account if you don't have one yet. GitHub is the largest hostof source code in the world, with over 30 million users.
Once you have your account, you'll need to tie the MakeCode web app to youraccount. To do that, open any project in https://maker.makecode.com, go to the Gear
Wheel menu on top, and select Extensions. At the bottom, there should be a link tolog in to GitHub. A dialog will appear asking you to generate a GitHub token. Follow
the instructions and paste the token into the dialog.

Once you've logged in, go back to the home screen. Now, the dialog that comes up
after you press the Import button will have an additional option to list your GitHub
repositories or create a new one.
Additionally, the Import URL option will now support https://github.com/...
URLs, which is useful if you can't find your repository in the list (especiallyorganizational repos), or as way to search the list faster using a copy/paste of theURL.

©Adafruit Industries

Page 11 of 15

If you import a completely empty repo, or create a fresh one, MakeCode willautomatically initialize it with pxt.json and other supporting files. If you import a nonempty repo without the pxt.json file, you will be asked if you want it initialized. Notethat this might overwrite your existing files.

Commit and pushOnce you have your repo set up, edit files as usual. Whenever you get to a stablestate, or just every now andthen to keep history and insure against losing your work, push the changes to GitHub.
This is done with a little GitHub sync button on top of the Explorer. The button will
check if there are any pending changes to check in. If there are, it will create acommit, pull the latest changes from GitHub, merge or fast-forward the commit if
needed, and push the results to GitHub.

©Adafruit Industries

Page 12 of 15

If there are changes, you will be asked for a commit message. Try to write something
meaningful, likeFixed temperature reading in sub-freezing conditions or Addedmysensor.readTemperature() function .
When describing changes, you are also given an option to bump the version number.
This is a signal that the version you're pushing is stable and the users should upgrade
to it. When your package is first referenced, the latest bumped version is used.
Similarly, if there is a newer bumped version, a little upgrade button will appear next
to the package. Commits without bump are generally not accessible to most users, sothey are mostly for you to keep track of things.
We do not really distinguish between a commit, push, and pull - it all happens at oncein the sync operation.
You can view a history of changes by following the version number link on the Project
Settings page.

There is also another button next to the GitHub sync - you can use it to add new files
to the project.
This is mostly to help keep the project organized. For our TypeScript compiler it
doesn't matter if you
use one big file or a bunch of smaller ones.
©Adafruit Industries

Page 13 of 15

Conflicts
It's possible that multiple people are editing the same package at the same timecausing edit conflicts. This is similar to the situation where the same person edits thepackage using several computers, browsers, or web sites. In the conflict description
below, for simplicity, we'll just concentrate on the case of multiple people working on
the same package.
Typically, two people would sync a GitHub package at the same version, and thenthey both edit it. The first person pushes the changes successfully. When MakeCodetries to push the changes from the second person,
it will notice that these are changes against a non-current version. It will create acommit based on the previous version and try to use the standard git merge (runserver-side by GitHub). This usually succeeds if the two people edited different files,
or at least different parts of the file - you end up with both sets of changes logicallycombined. There is no user interaction required in that case.
If the automatic merge fails, MakeCode will create a new branch, push the commit
there, and then create a pull request (PR) on GitHub. The dialog that appears after thishappens will let you go to the GitHub web site and resolve the conflicts. Before you
resolve conflicts and merge the PR, the master branch will not have your changes (itwill have changes from the other person, who managed to commit first). After creating
the PR, MakeCode moves your local version to the master branch (without yourchanges), but don't despair they are not lost! Just resolve the conflict in GitHub andsync to get all changes back. MakeCode will also sync automatically when you close
the PR dialog (presumably, after you resolved the conflict in another tab).

Testing your package
To test blocks in your package, press the New Project button on the home screen andgo to the Extensions dialog. It will list all your GitHub projects as available foraddition. Select your package and see what the blocks look like.
You can have one browser tab open with that test project, and another one with thepackage. When you switch between them, they reload automatically.
For testing TypeScript APIs you don't need a separate project, and instead canuse the test.ts file in the package itself. It is only used when you run the package
directly, not when you add it to a project. You can put TypeScript test code in there.

©Adafruit Industries

Page 14 of 15©Adafruit Industries

Page 15 of 15