1

Creating mBlock Extensions

by Wang Yu, Product Manager at Makeblock

Creating mBlock Extensions 2

How Extensions Work

Extensions allow custom blocks for mBlock. You can use
extensions to support third-party Arduino sensors or
other robotic products such as Lego or LittleBits.

Anybody can write extensions for mBlock. This makes

mBlock an awesome platform for every types of
hardware-related programming.

Scratch Mode and Arduino Mode

Every block in mBlock has two modes: Scratch Mode
and Arduino Mode. Its important to know their
difference before writing extensions. use Edit/Arduino Mode menu item to - Arduino Mode
toggle between Scratch and Arduino
In Arduino Mode, the
modes
program is uploaded
into the robot and the
robot is run on its own.
However, you cannot use
> Scratch Mode graphics from Scratch
In Scratch Mode, the since the computer is no
robot or Arduino board longer there.
must be connect to
the computer in order
to run the program. You
can use Scratch blocks to
create graphics or make
this Say block can only be used in
games.
the Scratch mode; while the (Repeat)
Forever block can be accessed in
both modes.
Creating mBlock Extensions 3

Using an Extension 2 You may search for extensions with the

search box. Click Download at the right of
Using the Extension Manager, you can browse the table item to download the extension.
extensions, find one you want, and get the blocks Internet connection is required.
included in the extension with a single click.
Extensions you can Extensions installed in this computer. You may
download from the Internet upgrade or remove those extensions
The following instructions shows how to add an
extension to mBlock.

1 Use the menu item Extensions, Manage

Click here to
Extensions to open up the Extension
download
Manager.

Read more information from

the authors webpage

Install an
extension from
a zip file in your
computer

3 The extension you downloaded will show up

in the Robots group of mBlock. These blocks come from
the Demo extension I
just downloaded
Creating mBlock Extensions 4

Writing an Extension Tips

Writing an extension is not as hard as it seems. Mostly it Source code of existing extensions are always the best resource
is done by editing some text files. Arduino knowledge in writing extensions. In mBlock, you can always view the source
code of existing extensions through the Extension Manager.
is required in implementing the Arduino Mode, while
Javascript is used in the Scratch Mode. You may skip one
of the modes, and the block will simply not work in that
mode.

Heres a list of things extension writers need to do:

Write basic information, such as the name and author Click here to view the source
code of any existing extension.
Define how the blocks look like
Tell mBlock how to generate the Arduino code
Write the functions run in the Scratch mode
Include additional Arduino header / C files. View Source will bring up a window of that extensions folder.
You may try to change the extension code and it will take effect in
the next time mBlock is launched (this is one way of debugging).
The File Structure of an Extension However, any changes made here will be discarded when
upgrading mBlock or running the clear cache command.
Every extension is a .zip file compressed from a folder.
Here is the folder of the Demo extension when
unzipped:

.s2e file: basic description, blocks

definition of the extension, and the
Arduino code generated by the
extension in the Arduino Mode. s2e
stands for Scratch 2 extension files

Javascript code that run on the

Scratch Mode stays in the js
src folder is for additional files
folder
included in the Arduino mode. You
may skip this if you dont use additional
libraries
Creating mBlock Extensions 5

1 Filling out Basic Information Tips

Download the Demo extension as a starting point at: the .s2e file is the main file of the extension. Aside from the basic
http://www.mblock.cc/site-images/Demo.zip information, it defines blocks, tells mBlock how the dropdown
menus look like, and how to translate the extension to another
The next step is editing the s2e file. You need a text language (if you want to).
editor. the Notepad program is fine, but I recommend If you are familiar with Javascript, you may notice it is written in a
editors dedicated for code editing, such as Github plain JSON (JavaScript Object Notation) object.
Atom, Visual Studio Code, Brackets, or Sublime text.

At the beginning of the .s2e file lies some basic

information. You need to tell the user what does the Basic information
extension do and who wrote it. Here is the starting lines
of demo.s2e:

Block definition

the purpose of the extension. Menu definition

name your extension It shows up in the extension
version number, in forms manager How menu items are
of x.y.z. It is used in transformed into numerical
updating the extension values in the Arduino Mode
Translations
your name, and email
address
The order of the extension when
show up with multiple extensions
A web page to read more
about the extension Location of the Javascript
firmware and file for Scratch mode
extensionPort are not
used, just leave it be
Creating mBlock Extensions 6

2 Defining Blocks
the blockSpecs section tells mBlock how blocks look / Block Types are indicated by a single letter:
like, and gives clues on how they behave in Scratch and h stands for header blocks; they are rarely used in
Arduino mode. custom extensions.

Every block is described w stands for write blocks; they send commands to
in a Javascript Array form the hardware and do not expect a response.
r is for reading blocks; in Scratch Mode, it waits
the function to return a value; R is for asynchronous
reading - the value is not returned by the function but
told later (callback) through a function in Javascript.
r and R looks the same and have no difference in
the Arduino mode.

b is for binary blocks; they return a binary yes-or-

no value. Similarly, B is for asynchronous reading of
binary values

/ The text that appears on the blocks

words begin with % are parameters - slots that users can fill up by typing or with
other blocks. This block (digitalWrite( %n , %d.digital )) looks like:

%n gives a round slot for numbers, and will %d.name gives a round dropdown box, and will give a
give a number in the Arduino Mode. number in the Arduino Mode. The dropdowns content is
defined in the menus section and identified by name.
Other parameter types include:

%s gives a rectangular hole for %m.name gives a rectangular %c gives a color picker
strings dropdown box for strings
Creating mBlock Extensions 7

3 Making Menus
the digitalWrite block has a convenient menu for
selecting HIGH or LOW output. It is defined in the
following way:

%d.digital means menu information is stored in the

digital list of the menus section

4 Finishing Up the Block Definition

give a Javascript function name

to use in the Scratch Mode

this means the menu has two options: give default values to the
HIGH and LOW block you just defined

in Arduino mode, HIGH generates a

value of 1 and LOW generates 0. This
does not affect the Scratch Mode.
Creating mBlock Extensions 8

5 Arduino Code Generation

When defining each block, .s2e file also decides how
Arduino code is generated, following rules below:

insert include
statements
define variables

insert once in the

setup() function

can appear many times

when the block is used

{0} means the first

parameter, 9 in this case

insert once in the

loop() function

if you included other source

files, be sure to copy them to
the src folder
Creating mBlock Extensions 9

demo.s2e
6 Coding Scratch Mode
The Javascript file is pretty long. I recommend take the
demo.js and only make necessary changes. If your extension
does not support Scratch Mode, skip this part.

demo.js file name

must match
demo.s2e
dont change

define your own variables here

function name
defined here
setup code for the extension

write code for your

blocks here

send bytes via the serial ports

using an array of bytes
this is called every time the computer
receives bytes from serial ports

trace(string) function is really useful for

debugging because it produces logs in the
Arduino Mode panel.
(at the end of) demo.js

change this to the name of your extension.

Creating mBlock Extensions 10

Publishing Your Extension 2 Upload your extension

After you are satisfied with the extension, zip it into a After Signing in, drag your .zip file to the large box (or
.zip file. In MacOS, right click the folder and choose click the large box to choose with a file browser)
Compress xxx...; in Windows, right click the folder
and choose Send To, Compressed (zipped) folder.

Then you may import the extension through the Add

Extension button in the Extension Manager. But Itll be
easier for the users if the extension is uploaded to the
Drag your .zip
Online Extension Center.
file here

1 Sign in with your Github account

Go to the extension center website:
http://www.mblock.cc/extensions/
Congratulations! Youve uploaded an extension and
And click Sign-in with Github. If you dont have Github
contributed to the world mBlock community!
account, you need to register one. Click here to
sign-in Tips
If you want to update your extension, simply upload a .zip file with
a higher version number. And youre all set.

Tips
Makeblock, the company maintaining mBlock, reserves every right
to remove an extension, with or without explanation. But we do
welcome extensions of every kind from every product and hope
we only moderate spam (like one with the name test123) and
those with improper content. Simply use your common sense.