The Adafruit products compatible with MakeCode Arcade are designed such that they can clip onto a lanyard without a case. (Many cases are also designed with lanyard clips). Hence the name for PyBadge - it can be worn as a badge. This is very similar to the current "badge life" craze at conventions to make electronic badges.

But what if you could customize the display with your own design. This guide will get you started with Microsoft MakeCode Arcade to just that. The steps are laid out slowly and carefully to ensure beginners can follow along and not assume prior knowledge of programming or MakeCode Arcade.

This tutorial is aimed at people new to programming and Microsoft MakeCode Arcade.

For advanced users, see this guide for more customizable features using CircuitPython.


Angled shot of a Adafruit PyBadge for MakeCode Arcade, CircuitPython, or Arduino.
What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino? That's right, its the Adafruit PyBadge! We wanted to see how much we...
Out of Stock
Angled Shot of Adafruit PyBadge - Low Cost.
What's the size of a credit card and can run CircuitPython, MakeCode Arcade or Arduino even when you're on a budget? That's right, it's the Adafruit...
Out of Stock
Angled shot of Adafruit PyGamer for MakeCode Arcade, CircuitPython or Arduino.
What fits in your pocket, is fully Open Source, and can run CircuitPython, MakeCode Arcade or Arduino games you write yourself? That's right, it's the Adafruit...
Out of Stock
Adafruit PyGamer Starter Kit with PCB, enclosure, buttons, and storage bag
Please note: you may get a royal blue or purple case with your starter kit (they're both lovely colors)What fits in your pocket, is fully Open...
Out of Stock

USB Cable Options

USB cable - USB A to Micro-B - 3 foot long
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or...
In Stock
The MakeCode Arcade main screen at

Microsoft MakeCode is a block based web coding environment. It is very similar to Scratch and other block based editors. You do not need to download any code on your computer. The web environment works best on Google Chrome which is available for PC, mac, and Linux.

MakeCode Arcade is a similar environment to MakeCode, but the environment has code blocks which are oriented towards building games. Most of the concepts used in game development on small devices are supported by MakeCode Arcade.

Documentation is available for MakeCode Arcade at


Makecode Arcade requires Google Chrome as the browser at this time. There are versions of Chrome for mac, PC, Linux, and Raspberry Pi.

No other software is required.

The back of the PyGamer board. The square at the center marked "Atmel" is the microcontroller.


Code in MakeCode Arcade can run on a few boards developed by different companies. Here, we will concentrate on the Adafruit MakeCode Arcade compatible boards:

Note this list may grow - if you are unsure if your Adafruit board is compatible, go to the product page on and see.

Each of the Adafruit boards have LCD color displays and buttons for game controls. All are currently based on the Microchip SAMD51 microcontroller.

Starting the MakeCode Arcade web application

On your computer, start the Chrome browser. Navigate to the website You should see the following opening screen:

To start a new project, you click the New Project box which has a white circle with a purple + inside (circled in red below):

You'll get the following screen which is where you can start coding:

The code creation view. See the named areas below, above numbered in orange.

The screen is divided into several areas. 

  1. The grey gaming device simulator - used to test your code on a software simulated game board.
  2. Code Block Groups - code blocks are grouped into various groups and color coded to make them easier to know to which group they belong.
  3. On Start code block - this is added for every new project - you may or may not need it, it is only put up as a possible starting point.
  4. Code Block Area - where you drag blocks from the Code Block Groups to make your program.
  5. Filename Save - when you are ready to save your code to your computer file storage, name the file here and press the floppy disk Save icon.
  6. Download Button - download the code to a Microsoft MakeCode Arcade-compatible board.

Our Goal: A Standard Name Tag

For this very simple first code ever, we'll make a name tag similar to the standard name tag below. The colors and content are easy to recognize, everyone expects your name in the white space.

Source: Wikimedia Commons - Eviatar Bach [Public domain]


We will start with that green block already on screen. On Start is a block in the Loops category of blocks. It doesn't loop though. It's purpose is to contain a series of other blocks when the board starts running our code which is what we want.

Background Color

The background we want is red, so we need a block that sets a red background. There is a block in the Scene block group (it has a blue tree next to it) called set background color to which is exactly what we want.

Click the word "Scene" to open up a set of blue blocks. The view is like this:

The view above is zoomed in some. You'll see a lot of blocks under Scene. We want the third one, set background color to. Using your mouse, left click and hold the mouse button on the block and drag it across the screen to the space inside the on start block as shown above. Release the mouse button and the block should be placed as shown below.

Underneath the simulator, you could run this code but the background color is blank, not exactly what we want. We need to change the grey square in the set background color to to red.

Left click that grey oval and select the color red. You should now see: 

As there is always a chance a mistake is made that cannot be easily corrected, or the power goes out or literally anything and everything, saving your work periodically is a good idea.

I suggest you use different file names at each step. Especially as later on you may be loading graphics from a program already saved and proceeding from there.

In the screen at left, the save box is located at the bottom of the screen.

Type in a filename and click the disk icon. Your computer will prompt you for a location to save your code.

You code is saved in a special PNG file. Yes, PNG stands for Portable Network Graphics and your code is encoded within an image file!

The clever Microsoft folks have devised a file that you can view on any type of computer and it also has code within it. So if you are confused as to where your code blocks are, they are within the PNG image.

You should see a pop up like that to the left after selecting the location to save your file explaining things.

Here is the PNG for the simple badge. Most of the PNG is a black image - we didn't do anything fancy to make a more colorful image but you will see some text to indicate what the image is.

If you want to upload my badge code, use the image below, right click the mouse and save it onto your computer.

In the MakeCode Arcade main page, you can upload this image and have the exact code I used already loaded.

Loading or Reloading Code

If you plan to load some code, you may wish to first save your progress so far. Do so now if you need to as loading a program replaces the work you have done and the process is not reversible.

Load your code via the main MakeCode Arcade page using the Import button shown in the screenshot at left.

When the code is loaded, you'll see the familiar code creation screen with the code blocks already positioned.

Next is to get the big white rectangle with your name in there.

Go back into the Scene block group and drag a set background image block to just under the set background color to block. Note: The on start "C" shape will expand to fit the two set background blocks.

The background image will be a white stripe with your name in it. To do this, click the grey square in the set background image to block.

Wow, that's more complex than a color choice popup. The block looks like MacPaint, Windows Paint, or other very basic image editors.

See the labels at left for what each item controls.

The idea is to make a white stripe with your name which is spelled out  in black. Select the color white from the color palette with a mouse click, the current color rectangle between the colors and the grey tools will turn white.

Now select the square tool. On the checkerboard drawing area, make a rectangle past the halfway point like in the picture at left. If you look closely you can see the white rectangle outline.

Now click the paint can spilling icon (bucket fill) and then click inside the white rectangle drawn in the previous step. That will fill the rectangle with the current color, white.

The Hack

You are free to customize every part of your badge including all the text. 

BUT, if you want your badge to look more like our example, without all the hand lettering (which cannot be automated at the time of this guide). you can load a blank badge image by saving the special code PNG file below, and opening it in MakeCode Arcade. It will be at this step except the "Hello my name is" and the white name band are already done. Believe me, this is the best way at present.

Use the steps outlined in loading code on the preceding page after saving your current progress.

To Letter Your Badge

To switch to black for lettering, click the color black in the color palette near the bottom-left. The rectangle between the colors and tools will turn black.

In the upper left are three size squares side by side. Click the middle one to set a broad "tip" for using our drawing pencil.

Select the upper left Pencil icon.

Very carefully write your name pixel by pixel on the white area. If you mess up and make a black pixel where a white one goes, you can click the counterclockwise Undo button on the bottom right. Or you may change the pencil color to white and fix it, then change the color back to black. This is the hardest part of this tutorial. If you find it hard, no problem, take your time. See my result after a bit of time. I chose a short name, chicken me, and my effort is not 100% which is fine, it will be viewed at a distance.

Adding your text (such as a name) in the white part of the name tag. You can faintly see the "Hello My Name Is" text above the white rectangle.

When you're done, click the Done button, on the lower right of the image editor. Your image will appear as a tiny icon in the set background image to block. You can click that icon anytime you want to edit the image and text.

Optional Extra Step

A steady hand is good when hand lettering text in a basic paint program. You can also edit the picture in Javascript, but it's not usually a beginner task. The benefit is you just edit some numbers and it's easier to see how things line up. Here are the steps:

Click the Javascript button in the top center of the screen. At any time, you can go to the block mode by selecting Blocks.

You'll get a new edit pane where the blocks are. It is only a small amount of code, so it seems.

You will see there is a "+" sign after the start of line 2, click that and you'll see a huge representation of the background.  Periods are background color, 1 are white, f are black.

I shrunk the browser view in Chrome to 50% to see more of the screen at left.

Edit the huge matrix of periods, 1's and f's to straighten lines and do other cleanup. Be sure each line has the same number of characters in it as the file originally had or errors will result (why I said backup your work previously).

The difference between 1's and f's for the name area is not so easy to distinguish.

Double check your work when done (that all lines are the right length, spaces between entries, etc.

Now when you click the Blocks button, you should see the block code you had. The graphic square will be too small to see changes. Click the simulator Play button to see your changes easier.

See the next page for more seeing your results.

The code now consists of three blocks. Let's see what they do! Press the play button under the simulator on the left side of the MakeCode Arcade screen (circled in red by me in the screen above).

Success! We now have something that looks like a name badge. The text "Hello my name is" is not there, you can add that in the image editor or it can be added later, but no one will notice much. 

Uploading your code to your hardware is next.

Let's load a game! For example, here's a link to Run, Blinka, Run! To open the game in the MakeCode Arcade editor, first, click the share link below. This will allow you to play the game in the browser right away.

Then, click on the Show Code button in the upper left corner. The shows the code for the game, and by clicking the Edit button in the upper right corner, it'll open into the editor where you can upload it to your PyGamer/PyBadge.

Once you have a game working on the MakeCode Arcade web editor, it's time to download it and flash it onto your board.

Please only use the Google Chrome browser with MakeCode! It has WebUSB support and seems to work best

Board Definition

In order to load a game made in MakeCode Arcade onto the PyBadge, first choose the proper board definition inside of MakeCode. Click the ellipsis (...) next to DOWNLOAD and then the Choose Hardware item.

Change Board screen

Click on the image of your board, either the PyBadge/PyBadge LC or the PyGamer

This will cause the game .uf2 file for your particular board to be saved to your hard drive. You only need to do this the first time you use a new board. Thereafter you can simply click the Download button on the MakeCode Arcade editor page.

A HUUUUUUGE number of people have problems because they pick a 'charge only' USB cable rather than a "Data/Sync" cable. Make 100% sure you have a good quality syncing cable. Srsly, I can't even express how many times people have nearly given up due to a flakey USB cable!

Bootloader Mode

Now, we'll put the board into bootloader mode so we can drag on the saved .uf2 file. On the back side of the board you'll see a reset button at the top. Make sure the board is plugged into your computer via USB with a USB micro B to A data cable. Also, be sure the board is turned on.


Then, press the reset button. This will initiate bootloader mode.


When the board is in bootloader mode you'll see a screen similar to this one show up.

Drag and Drop

Now that the board is in bootloader mode, you should see a BADGEBOOT drive show up on your computer as a USB flash drive. Simply drag the arcade game .uf2 file onto the drive.


That's all there is to it! Once the file is copied over the board will restart and launch the game!

Keep an eye on for additional game related content.

Above you can see the code loaded onto two MakeCode Arcade compatible devices, an Adafruit PyBadge and an Adafruit PyGamer (enclosed in the Adafruit acrylic case).

Lanyard Connections

Lanyards with dial clips may mount onto the top holes of the Adafruit PyBadge and PyPortal / PyPortal LC devices (the holes are circled in red below).

Adafruit sells two compatible lanyards, one in black and one with Circuit Playground characters on it. Similar lanyards are available from other sellers or perhaps a custom lanyard could be procured for an event by a third party seller.

Portable Power

Both devices have the capability to use a small LiPo rechargeable battery. If you want to make your badge portable, install a battery on the rear and plug it into the indicated JST connector. (circled in purple above). See the PyBadge or PyGamer pages for the exact model to use.

Changing the Text

Notice the project earlier left out the "Hello, my name is" part. Part of this was for time and part to avoid additional work. You can add it if you like as follows:

Starting after the page Adding Your Name where you use the background image editor.

Select the color White and the appropriate pencil size above the pencil icon. Then click the pencil tool.

Carefully edit in, above the white rectangle, the text you want, like "Hello my name is". It will not be easy to see with the hatch background though. You might consider using a color other than white. Then if you want white, use the bucket fill to carefully fill the letters in with black (tricky).

Additionally, you can use the editor to change the name on the badge. Feel free to save multiple copies of your badge in different files for easy switching.

Changing the Colors

In the set background color box step, feel free to use a different color. You can experiment using the simulator to see what affects your changes have.

In the set background image step, you can draw anything you like.

Have fun customizing your badge.

More advanced badge making

The badge on the front page was actually made in a different tutorial (sorry about that).

The tutorial PyBadge Conference Badge with Unicode Fonts uses the CircuitPython programming language to automate much of what we did in the drawing tool by hand. This is at the expense of more complexity in use.

Actually it is not difficult to select your choices and upload to CircuitPython. Feel free to explore doing this.

This guide was first published on Jul 31, 2019. It was last updated on Mar 08, 2024.