Building an extension for MakeCode for micro:bits

 

I have built a couple of extensions for MakeCode, but it was not without pain. The trouble is that the writers of the documentation, such as Building your own extension, don't know my limitations (I'm not a professional coder, for one). So I'll try and show you one way to do the job - there are other ways which may suit someone who is familiar with Node.js and so on, but I'm more at home using a browser. A browser and a text editor are all you will need!

I'll use my Bitwise Logic extension as an example. The functions operate on each bit of a number and are very useful when we are interfacing a micro:bit to other electronic devices.

The first thing to do is to work out which blocks you want to create. I'll start with a really simple block - it provides the bitwise NOT function. In JavaScript that is represented by the ~ operator. So to invert each bits of the variable called a you would write:

~a

In our blocks view of the world we want  to make a block like this:

As an example, the bitwise NOT of the number 3 (0000 0011b in binary notation) is 1111 1100b if we are using 8-bit numbers.

Building a block

There is quite useful documentation on how to code the block so you can get it to look and behave the way you want, and the best place to learn more and experiment is the playground. This has lots of examples and you can try various ideas until you get what you want. 

By the way, the playground is not just for micro:bits, because MakeCode is used for other targets as well like Arcade and Minecraft. You will need to set the target to micro:bit before doing anything!

Here is the code for the example block (the code "language" is called TypeScript, which is a superset of JavaScript):

//% blockId="bitwise_not" block="~ %a"
export function bitwiseNot(a: number){
    return(~a)
}

 The key thing to look at here is the block="~ %a" text; this defines how the block looks. It is telling the MakeCode editor to display a tilde (~) followed by a parameter called a. The user can type a number into the parameter's white circle, or another block can be inserted into the circle.

Your blocks need to be written inside a namespace - which will be the name of your extension:

namespace BitwiseLogic {

    (block code goes here)

}

Here's a view of the playground and the micro:bit editor:

Building your extension

Tip! You may need to force-refresh your browser (typically Ctrl F5) occasionally to make sure you are seeing any changes made in other tools like the text editor or GitHub.

Once you have tested your block you can copy the code into a text file. You can call it main.ts (ts stands for Typescript), but you don't have to. 

I would advise uploading that file to Github - you will have to do that at some stage, and it's best to learn to use it sooner rather than later! Here is a good guide to get started.

I have found some problems with setting up a repo (short for repository - that is just a name for a bunch of files) so that it is compatible with MakeCode. The best way IMHO is to:

• create a new project in the MakeCode editor
• name it: pxt-your-extension-name, e.g. pxt-BitwiseLogic
• save it to GitHub  using the blue/white button at the bottom of the screen
  
  
  
  
  
  
  
• this creates a number of files, many of which you don't need. For now, just use main.ts to save your block code in.

Testing your extension

You can keep copying your main.ts into the playground on the left-hand side, and then build some test programs using blocks on the right-hand side, but another way to do it is to use the normal MakeCode editor and access your extension via GitHub. Of course, once your extension has been approved, it will appear in the official Extensions list.

You can do your testing in MakeCode by creating a new project - I recommend first going to Settings (the gear wheel) and doing a Reset from the drop-down menu.

Then, in the list of blocks, click on Advanced and scroll down to Extensions. Now paste in the URL of your Github repo:

Now your extension package will pop up:

and your blocks will appear in the list:

Now you can start to design your test code!

.