Overview

Microsoft MakeCode for Adafruit is a web-based code editor for physical computing. It provides a block editor, similar to Scratch or Code.org, and also a JavaScript editor for more advanced users.

If you just want to use MakeCode to build programs, you can visit https://makecode.adafruit.com/, and check out our basic guide to MakeCode as well as instructions for using MakeCode with the CircuitPlayground Express.

MakeCode is built on the Microsoft Programming Experience Toolkit (PXT), which powers editors for a variety of hardware platforms.  This guide offers concise instructions for installing the MakeCode for Adafruit project on a system you control.

This guide is just for people who want to do development ON MakeCode, to add more capabilites or maybe just run a local version that does not require 'the cloud'!

Installing on Debian and Ubuntu Desktops

If you're using a recent stable Debian or Ubuntu release, you can install and run a development version of of MakeCode directly on your system. (For a more contained solution that should work on Windows or MacOS, skip ahead to the next section of this guide.)

First, open a terminal and create a new directory to contain the PXT code repositories by typing the following commands:

mkdir makecode-adafruit
cd makecode-adafruit

Next, create a file called install-makecode.sh with nano, or the text editor of your choice:

nano install-makecode.sh

And paste the following script into the file:

Download: file
#!/bin/sh

# Install Node.js:
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install some dependencies:
sudo apt-get install git libsecret-1-dev
sudo npm install -g jake
sudo npm install -g typings
sudo npm install -g pxt

# Clone repos from GitHub:
git clone https://github.com/Microsoft/pxt
git clone https://github.com/Microsoft/pxt-common-packages
git clone https://github.com/Microsoft/pxt-adafruit

cd pxt
npm install
typings install
jake

cd ..
cd pxt-common-packages
npm install
sudo npm link ../pxt

cd ..
cd pxt-adafruit
npm install
sudo npm link ../pxt
sudo npm link ../pxt-common-packages

Save the file and exit (in nano, press Ctrl-X, followed by y and Enter to write the file).

The script installs Node.js, the Git version control system, and several other dependencies. It then checks out the latest development versions of the PXT code and installs it.

Run it with:

sh install-makecode.sh

This should take quite a while to finish.

Now you can run the following at the command prompt:

cd pxt-adafruit
pxt serve --cloud

This step will also take quite a while the first time you run it, since it needs to build various resources.

Eventually, MakeCode should print something like the following...

starting local ws server at 3233...
---------------------------------------------

To launch the editor, open this URL:
http://localhost:3232/#local_token=0918998d-feec-4217-3c97-41d14634b51f&wsport=3233

---------------------------------------------
opening http://localhost:3232/#local_token=0918998d-feec-4217-3c97-41d14634b51f&wsport=3233

...and then open in your web browser:

You can press Ctrl-C in the terminal to stop the MakeCode process. To start it again, just remember to cd to the project directory and run pxt serve --cloud again:

cd ~/makecode-adafruit/pxt-adafruit
pxt serve --cloud

Installing with Vagrant

Vagrant is a tool for managing and configuring virtual machines. You can use it to run a development installation of MakeCode which can build the static version of the MakeCode site, like the one hosted at makecode.adafruit.com.

First, you'll need to install Vagrant, VirtualBox, and Git.  We have a guide to installing these tools on Windows.

Next, you'll need a copy of the git repository here:

https://github.com/adafruit/Adafruit-PXT-Setup

Start Bash, and clone the repository:

Download: file
git clone https://github.com/adafruit/Adafruit-PXT-Setup.git
cd Adafruit-PXT-Setup

Start and provision the Vagrant box:

Download: file
vagrant up

This part will take a while, particularly on a slow connection, since it has to download both the image for the virtual machine and a bunch of dependencies.  When it finishes, you should see the string "setup.sh completed" as the last message it prints out.

Now you can SSH into the Vagrant box and build MakeCode itself:

Download: file
vagrant ssh
cd pxt-adafruit
pxt staticpkg -o /var/www/html

This will take a while, and may fail with a long error message on the first attempt.  If so, run pxt staticpkg -o /var/www/html again.  When it finishes, you should see something like:

Download: file
...
rendering docs/tutorials/sensors/graph-acceleration.png
rendering docs/tutorials/sensors/graph-lightlevel.png
rendering docs/tutorials/sensors/graphblock.gif
rendering docs/tutorials/sensors/lightlevelblock.gif
rendering docs/tutorials/sensors/sensors.md
rendering docs/tutorials/siren.md
rendering docs/tutorials.md
rendering docs/windows-app-web-link-ref.json
Docs written.

Now, as long as the Vagrant box is running, you should be able to load MakeCode for Adafruit from your local system.  Open up a browser and load the following URL:

http://localhost:8080/

...this works because port 8080 on your system is forwarded to port 80 on the Vagrant box, which is running a webserver to serve the generated files.

This guide was first published on May 23, 2018. It was last updated on May 23, 2018.