Editors like MakeCode and Scratch 3 both have “Extension” features in which you can add support for multiple add-on boards for things like the micro:bit. Until now, adding support for an add-on board for the micro:bit in EduBlocks has not been possible, until now.

Back in July I wrote a post on how to add a library to EduBlocks for the Raspberry Pi. The process is similar but slightly different for the micro:bit, so here is how to make a micro:bit extension!

NOTE: IF YOU’RE A DEVELOPER AND WANT TO TEST YOUR BLOCKS PROPERLY, PLEASE CLONE THE REPO ON YOUR MACHINE AND FOLLOW THE INSTRUCTIONS AT https://github.com/AllAboutCode/EduBlocks#developer-instructions TO RUN EDUBLOCKS AND TEST. SKIP STEP 1 IF YOU DO THIS

Step 1 – Fork the Repo

This is a fairly easy task, navigate your browser to http://github.com/allaboutcode/edublocks. You will be presented with the Repo page, locate the Fork button as shown below and click on it to make a copy of EduBlocks on your GitHub account.

Once you have clicked the button, GitHub will tell you that it’s forking the repository and then it will present you with the EduBlocks repo again, but this time, it’s a copy connected to your account.

Click on the button that says Branch: tarball-install and change it to microbit.

Step 2 – Create the libary folder and setup

Now onto actually creating the library. Navigate to the following folder (ui/src/blocks) on GitHub, it will look something like this.

This is the folder in which we will create our blocks. The first thing we need to do is create a folder and then a file called definitions.ts. To create a folder click Create new file and then type mylib into the text box next to ui/src/blocks (replacing mylib with the name of the library your adding) and then press the / key on your keyboard. To create the file, you simply just type definitions.ts in the text box you just typed in to create the folder. Once you have done this, scroll down to the bottom and press the green Commit button. Follow the gif below to do this.

Now we need to create two more files, generators.ts and toolbox.xml. To do this, follow the same procedure as before, but this time you don’t need to create a folder. The gif below demonstrates how to create these files.

Then create another file and call it mylib.py replacing mylib with the name of the library. In this file, add your micro:bit micropython library.

Step 3 – Add your library to the index

Now we need to add your library to the index file, this is so that your library appears in the blocks list. The file is located in ui/src/blocks and is called index. ts.

Click on the file and select the pencil icon, this will bring the file into editing mode.

Once the file has entered editing mode, in the text window, scroll down to the bottom of the file, this is where we need to add some code. The highlighed section in the image below shows where to add the code.

Add this code, replacing mylib with your library name (the name that you called your folder).

import mylibDefs from './mylib/definitions';
import mylibGens from './mylib/generators';
mylibDefs(Blockly.Blocks);
mylibGens(Blockly.Python as any);
const mylib = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'blocks', 'mylib', 'toolbox.xml'));

Once you’ve added that bit of code, click on the green Commit button.

Step 4 – Setup Definitions, Generators & Toolbox files

Now we need to add some code to our Definitions, Generators & Toolbox files. Navigate to your mylib folder and click on the definitions.ts file, and put it in editing mode by clicking on the pencil icon.

Add this code into the file:

export default function define(Blocks: Blockly.BlockDefinitions) {


}

Press the green Commit button and now go into the generators.ts file and put it in editing mode. Put it in editing mode and add the following code:

export default function define(Python: Blockly.BlockGenerators) {


}

Again, press the green Commit button to save that file. Once you’ve done that, go into the toolbox.xml file and put it in editing mode. Add the following code, replacing mylib with the name of your library. Where it says colour = 200 replace that with a number 1-360, make sure that it is a different colour to the other libraries already in EduBlocks though!!:

<category name="mylib" colour="20">

</category>

Press the green Commit button again for this file.

Step 5 – Setup your library as an extension.

Navigate to the file ui/src/app.ts and add your library to this function, it should be around line 56. Once you’ve done that, commit the file.

function getExtensions(): Extension[] {
    return [
      'scroll:bit',
      'mylib',
    ];
}

Now head over to ui/src/app.ts and add your library to this type variable, it should be around line 33:

type Extension = 'scroll:bit' | 'mylib';

Also, around line 29, you need to add some code and make some adjustments, you should see something looking like this:

var scrollbit = 'from scrollbit import *'
var mylib = 'from mylib import *'
var newpython = python.replace(scrollbit + mylib, '')

After you’ve done that and commited it, add this code to ui/src/blocks/index.ts:

if (extensions.indexOf('mylib') !== -1) {
    toolBoxXml += mylib;
  }

function getBeforeScript(extensions: Extension[]) {
  if (extensions.indexOf('mylib') !== -1) {
    return fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'blocks', 'mylib', 'mylib.py'));
  }
}

That’s it, you’ve now registed your library as an extension!

Step 6 – Create a block and add it into EduBlocks.

Now onto creating a block, this is simple thanks to the Google Blockly Developer Tools. We shall show you a range of different block types and you can pick an choose what you want to do with them.

Point your browser to https://blockly-demo.appspot.com/static/demos/blockfactory/index.html. This will present you with the following page:

The first thing you need to do is change 2 things. In the Block Definition and Generator Stub sections, we need to change the Definition box to Javascript from JSON and the Generator box to Python from Javascript. The gif demonstrates this.

On the left hand side of the page, you will see a block editor. This is where we make the blocks. Let’s create a simple block that will import our library.

Simple text block

Make the block

Make sure that when adding an import block, you do so in the format “from mylib import *”

The first thing we need to do is change the name of the block in the big green block, this currently says block_type. Change this to import_mylib replacing mylib with the name of your library.

In the green block, where it says No Connections click on the dropdown and select top+bottom connections.

Where it says Tooltip in the blue block next to it, in the text field type what your block does, in this case Imports mylib. This is optional.

In the colour box, change this to the number you selected from 1-360 earlier, note that in EduBlocks the colours are more vibrant.

Your block should now look like this:

Now lets add some text. From the grey sidebar next to your green block, click on Input and drag Dummy Input into your green block in the big gap underneath import_mylib.

Once you’ve done that, click on the Field button in the grey sidebar. Then drag a text block into the Dummy Input block. Inside the text box in the text block, type in the Python code for that block. For example, an import block would say import mylib. You will now see your finished block in the Preview section.

Below is a gif of how to do all of this.

Add the block to EduBlocks

Now we need to add our block into EduBlocks. Go back into GitHub and open up the Definitions file and put it in editing mode. We will be adding some code into this section:

Go back into the Google Blockly Developer Tools tab (the program you used to create the block) and highlight and copy the following part of this code in the Definitions section.

Paste that code into the section that we highlighted in red earlier in the definitions.ts file. That file should now look something like this. If it does, click the green Commit button.

Now open the generators.ts file and put it in editing mode. We shall be adding code to this section:

Go back into the Google Blockly Developer Tools tab (the program you used to create the block) and highlight and copy the following part of this code in the Generator Stub section.

Paste that code into the section that we highlighted in red earlier in the generators.ts file. The file should now look like this.

We now need to add the python code into the generator. Locate where it says var code = '...\n';. Remove the ... and type in the python code you want to run when this block is used, for example if your making an import block you would add import mylib. Your code should now look like this:

Press the green Commit button to save that file. Now we need to add our block into the toolbox, open the toolbox.xml file and put it into editing mode. Add the following code into this highlighted section, replacing the import_mylib with whatever you have called your block.

<block type="import_mylib"</block>

Press the green Commit button to save that file.
Congratulations, you have just added your first block into EduBlocks!

How do I add a text input?

You can also add text inputs and other fields into your block. They can be found in the Fields section of the grey toolbar. Create a block that looks something like the one underneath.

Copy and paste the definitions and generators like you did in the previous steps but this time the code variable in the generator is going to look different.

Make a note of the second text field of the text input block, you’ll need this later. In the generators file, we need to specify the text field. This can be done by saying +text_input+ where you want the input to go. Follow the gif below on how to do this.

Step 7 – Submit a pull request

Now we need to add our code to the main EduBlocks repository. This can be done by making a Pull Request, this is GitHub’s way of adding code to different repositories. Go to https://github.com/AllAboutCode/EduBlocks/pulls and click the green New Pull Request button.

Make sure that the Base fork and Head fork are correct. You should see something like this if everything is ok. Click on the Green Create Pull Request button to bring up the next window.

Add a title and description and again, click the green Create Pull Request button.

That’s it! You have added a library to EduBlocks. The owner of the repo (me) will check and test your code and merge it, so keep an eye out.

Let me know in the comments if you found this guide helpful!

Categories: Tutorial

Leave a Reply

Your email address will not be published. Required fields are marked *