Get Started
Getting started with MicroBlocks is easy! Just follow these simple steps.
You’ll need a computer (not a mobile device!) with a USB port, a USB cable, and a board. You can run MicroBlocks in a Chrome or Edge browser, or download a standalone app for Chromebook, Windows, MacOS, or Linux.
Computer Setup
How to set up your computer to use MicroBlocks.
No Setup Needed!
You don't need to install anything to run MicroBlocks in a Chrome or Edge browser; just click Run in the navigation bar at the top of the screen.
Running MicroBlocks in the browser avoids the need to install a conventional application, a process that often requires IT assistance.
MicroBlocks will run in other browsers, but it can only connect to a board when run in Chrome or Edge on a desktop, laptop, or Chromebook computer (not a mobile device).
Optional: Save the MicroBlocks Web App
For convenience, you can save a copy of MicroBlocks as a "progressive web app" that you can launch via a shortcut icon like a conventional application. Once saved, the MicroBlocks web app even runs offline!
To save the MicroBlocks web app, run MicroBlocks in your browser, then click the install button on the top right of the browser's URL bar:
Chrome:
Edge:
That will install the web app and open MicroBlocks in a new window. It will also add a shortcut to your desktop so you can launch the web app later.
Chromebook Setup
Google is phasing out Chrome apps. Thus, for most Chromebook users, it is better to run MicroBlocks in the browser instead of installing the app.
However, some older Chromebooks have reached their end of life and cannot be updated to a version of Chrome that supports webserial (v89 or later). Fortunately, such Chromebooks can still run the MicroBlocks Chrome app.
Go to the Download page and click the Download button. If are on a Chromebook, that will bring you to the MicroBlocks page on the Chrome Web Store.
Click the Add to Chrome button to install the app.
To run, open the Chromebook app launcher and click the MicroBlocks bunny icon.
You can pin the MicroBlocks app to make it easy to open in the future.
Windows Setup
Go to the Download page and click the Download button.
In Chrome or Edge, you will be warned that the downloaded file could harm your computer.
Click the three-dot menu and select Keep.
You will then get another warning. Click Show more and Keep anyway.
Open the saved file, microBlocks setup.exe.
After one more warning, that will open the installer.
Click through the installer screens to install the app.
The installer will launch MicroBlocks when it is done. It will also add a shortcut icon to the Desktop that you can use to run MicroBlocks later.
MacOS Setup
Go to the Download page and click the Download button.
Open the Downloads folder on your computer. Double-click MicroBlocks.app.zip to unzip it.
Right-click on MicroBlocks.app and select Open. A dialog will inform you that the app was downloaded from the Internet.
Click the Open button.
Although it will seem that nothing happened, you can now open the app by double-clicking it.
To finish, drag MicroBlocks.app to the Applications folder and drag MicroBlocks.app.zip to the trash.
Troubleshooting
If you cannot open MicroBlocks.app, open System Preferences… from the Apple menu and select Security & Privacy. In the General tab, make sure that Allow apps downloaded from: is set to App Store and identified developers.
Linux Setup
Go to the Download page and click the Download button.
The browser will give you the option to save the file or open it with Software Install. Select open.
Click the Install button. Enter the root password when prompted and click Authenticate.
The first time you install MicroBlocks you must reboot. The installer adds the user to the access group for the serial port, but that change does not take effect until the next reboot.
Troubleshooting
If Software Install does not work, click the Download button and save the file instead of opening it.
Open a terminal and run (for 64-bit):
sudo dpkg -i ~/Downloads/ublocks-amd64.deb
or (for 32-bit):
sudo dpkg -i ~/Downloads/ublocks-i386.deb
If MicroBlocks does not connect to your board, make sure that you rebooted after running the installer. Then run:
groups
to verify that you are in the dialout and tty groups.
To verify that Linux sees your board, make sure the board is plugged in, then run:
ls /dev | grep ACM
You should see an entry for your board, usually ttyACM0.
In 2022, some Linux distributions, including Ubuntu and Mint, began installing by default a package called BRLTTY (short for Braille TTY). Unfortunatley, that package conflicts with microcontroller boards that use the CP210x USB-serial chip, including many supported by MicroBlocks. BRLTTY grabs these boards so that no entry for the board appears in in /dev. This problem can be solved by removing the BRLTTY package:
sudo apt remove brltty
Board Setup
How to set up your board for MicroBlocks.
micro:bit (v1 or v2)
Connect the board to your computer.
From the MicroBlocks menu (gear icon), select update firmware on board.
The yellow LED will flicker as the firmware is installed. It takes a few seconds.
If you are running the MicroBlocks app, MicroBlocks will connect to the board automatically when it is done.
This video shows these steps.
Extra Steps in Browser
If you are running MicroBlocks in the browser or as a web app, you need to help the browser. (For security reasons, the browser cannot access the board's USB drive without asking the user.)
First, select your board type from the menu.
A dialog box will appear. Read the instructions, then click OK.
In the browser's save dialog, select the MICROBIT drive, then click the Save button.
You will see the orange light on the board flicker several times as the firmware is installed. At the same time, you will see a progress indicator on the screen.
When it is done, click the USB icon to connect to the board.
Circuit Playground Express or Bluefruit
Connect the board to your computer. Quickly click the small reset button in the center of the board twice.
The LED's will turn red for a few seconds, then turn green and stay green.
If they don't turn green the first time, try again.
From the MicroBlocks menu (gear icon), select update firmware on board.
Firmware installation takes just a few seconds. If you are running the MicroBlocks app, MicroBlocks will connect to the board automatically when it is done.
This video shows these steps.
Extra Steps in Browser
If you are running MicroBlocks in the browser or as a web app, you need to help the browser. For security reasons, the browser cannot access the board's USB drive without asking the user.
First, select your board type from the menu.
You'll be asked to select the USB drive for the board in the browser's file save dialog.
Follow the instructions to save the firmware file on your board. When the file is saved (just a few seconds), click to USB icon to connect to it.
Adafruit Clue
The process for installing firmware on the Clue is identical except that the reset button is on the back of the board.
and the Clue has only a single NeoPixel that turns green. (It's on the back of the board just below the USB connector.)
Calliope mini
Connect the board to your computer.
From the MicroBlocks menu (gear icon), select update firmware on board.
The yellow LED will flicker as the firmware is installed. It takes a few seconds.
If you are running the MicroBlocks app, MicroBlocks will connect to the board automatically when it is done.
Extra Steps in Browser
If you are running MicroBlocks in the browser or as a web app, you need to help the browser. (For security reasons, the browser cannot access the board's USB drive without asking the user.)
First, select your board type from the menu.
A dialog box will appear. Read the instructions, then click OK.
In the browser's save dialog, select the MINI drive, then click the Save button.
You will see the orange light on the board flicker several times as the firmware is installed. At the same time, you will see a progress indicator on the screen.
When it is done, click the USB icon to connect to the board.
Raspberry Pi Pico (RP2040)
Connect the board to your computer while holding down the white BOOTSEL button.
From the MicroBlocks menu (gear icon), select update firmware on board.
Firmware installation takes just a few seconds. If you are running the MicroBlocks app, MicroBlocks will connect to the board automatically when it is done.
Extra Steps in Browser
If you are running MicroBlocks in the browser or as a web app, you need to help the browser. For security reasons, the browser cannot access the board's USB drive without asking the user.
First, select your board type from the menu.
You'll be asked to select the USB drive for the board in the browser's file save dialog.
Follow the instructions to save the firmware file on your board. When the file is saved (just a few seconds), click to USB icon to connect to it.
Citilab ED1, M5 Stack, and other ESP32 and ESP8266 Boards
Board setup is similar for the Citilab ED1, M5 Stack, M5 StickC, M5 StickC+, M5 Atom Matrix, and other popular boards based on the ESP32 and ESP8266 such as the NodeMCU and Wemos D1 Mini.
Connect the board to your computer.
From the MicroBlocks menu (gear icon), select update firmware on board.
Select your board type from the menu.
If you are running MicroBlocks in the browser, you will be asked to select the board if it is not already connected.
MicroBlocks will start the firmware install process.
Note: Some ESP boards will connect only if you hold down the Flash or Boot button at the start of the firmware installation process. You can release the button when the progress indicator appears.
Once MicroBlocks has connected the board, you will see a progress indicator as the firmware is installed.
For ESP32 boards, the progress sequence will repeat several times as different parts of the firmware are installed. The firmware installation process can take several minutes.
When the process completes, MicroBlocks should reconnect to the board.
If MicroBlocks fails to reconnect after installation, quit and restart MicroBlocks (when running in the browser, reload the page).
Troubleshooting
Firmware installation on ESP32 and ESP8266 boards can be tricky.
Some boards require you to hold down the Flash or Boot button to start the installation process.
On other boards, firmware installation may fail randomly, not only with MicroBlocks but with other tools as well. You may need to try several times.
It sometimes helps to unplug the board, quit and restart MicroBlocks (or, when running in the browser, reload the page), then plug the board in and try again.
Fortunately, ESP boards work well with MicroBlocks once the firmware is installed.
Start Coding!
How to open the MicroBlocks editor and connect your board.
To run MicroBlocks in the Chrome or Edge browser, click Run in the navigation bar at the top of the screen.
Plug in your board, then click the USB icon.
Select your board from the browser dialog, then click Connect.
If you have installed the MicroBlocks firmware (see Board Setup) a green circle should appear behind the USB icon.
For a quick introduction to using MicroBlocks, check out this video (micro:bit) or this one (Circuit Playground Express or Bluefruit). You can also explore the user guide and blocks reference manual.
Click on the bunny icon to launch the MicroBlocks application.
Plug in your board. If you have installed the MicroBlocks firmware (see Board Setup) a green circle should appear behind the USB icon.
For a quick introduction to using MicroBlocks, check out this video (micro:bit) or this one (Circuit Playground Express or Bluefruit). You can also explore the user guide and blocks reference manual.