The picture below shows the principal areas of the MicroBlocks editor.
This area contains all the block categories that are used to program in MicroBlocks. They are grouped in nine color-coded groups. As categories are selected, corresponding blocks in that category will be listed in the Blocks Palette area next to it.
For a detailed description of all the blocks, please refer to the Blocks Reference.
Provides three system menus, as well as the Graph and Connect icons. These are described in detail below.
Displays the name of the project in the scripting area.
As new programs are loaded to the IDE, or existing scripts are edited, this indicator shows the progress of synching to the attached microcontroller board. Note that while this icon is visible, you will not be able to perform any editing in the IDE, until the activity is completed.
These consist of two icons, Start and Stop, that are used to control the execution of the MicroBlocks programs.
Start button simulates a micro device power-on by executing all event driven blocks like when started and when [condition].
The contents of this area reflects the various libraries that are loaded depending on the requirements of the user scripts and micro devices. It could range from totally empty to quite a few. For a detailed description, see Libraries below.
As selections are made in the Block Categories area, blocks with those specific functionalities will be listed in this area. From here, the blocks are dragged and dropped onto the Scripting Area to write programs.
If blocks in the Scripting Area need to be deleted, they can be simply dragged into this area. A trashcan icon will be visible to indicate this possibility.
If a Custom Block Definition in the Scripting Area is moved to this area, it will not be deleted, but rather hidden. To indicate that, an eye icon with a bar over it will be visible.
This is the main surface of the MicroBlocks environment where all the coding activities occur. Blocks are dragged and dropped onto this area to build up user scripts and custom blocks (functions).
As the mouse is moved over the various blocks and IDE areas highlighted in yellow, this area displays the type of the block and a short help info about the blocks; as well as the functionality of the various areas. Detailed block information is available through the right-click menu of each block.
These three controls enable one to resize the blocks up (+) or down (-), as well as set them to the default (=) size.
Since the scripting area is the most heavily used part of the editor, it is helpful to mention the operations and use conventions particular to this area.
Blocks that are placed into the scripting area can be freely moved around with the mouse.
Additionally, there various operations one can perform on the blocks and scripts placed here.
Blocks can be manipulated by keyboard controls, as well as the mouse and the R-Click block menus.
Keybard shortcuts are used with the combinations of CONTROL and SHIFT keys:
CONTROL means duplicate
SHIFT means "extract or duplicate just one block"
(i.e. not all the blocks in the sequence below it)
Drag (no modifiers) extracts the block and any blocks below it, as always
Control-drag is the same as "duplicate all"
Shift-drag is the same as "extract block"
Control-shift-drag is the same as "duplicate block"
As mentioned above, drag and drop movement of the blocks is all too familiar to almost everyone who has spent some time with block based development environments (Scratch, SNAP!, MakeCode, etc).
What is different and very nice in Microblocks is that a block that is clicked on gets a nice drop shadow which highlights it against the background. This 3D effect makes it easy to perceive that the targetted block is in fact in motion, floating over the scripting area surface, even above other script blocks.
As single or groups of blocks that are moved with the mouse, approach other blocks nearby, a horizontal white line will appear, designating a snapping point.
If one releases the mouse at that moment, the blocks under the mouse will snap to the blocks on the other side of the white line.
Right clicking any block within a group of blocks (script) will display a block level menu.
Selecting it will make a copy of the single block the mouse is positioned on.
Certain blocks (C-Blocks, IF-Blocks) may contain a bunch of other blocks within.
When duplicate is applied to one of these blocks, then the entire group will be duplicated.
This option is similar to the duplicate, with the difference being that, it duplicates all blocks below the selected one.
Based on the example we have been using, clicking on the repeat block and selecting duplicate all will duplicate the repeat block and all of the blocks under it.
Here again, the point to remember is that, if the "blocks below" are within a C-Block, then duplicate all is constrained to the C-Block.
Second example shows what happens when the first block within the repeat block is clicked.
Only the blocks within the repeat block are duplicated.
One of the pitfalls of block programming is that it is rather cumbersome to manipulate individual blocks that are in the middle of a group of blocks.
MicroBlocks is one of the few IDEs that handles this very gracefully, by providing a means to extract a block from a group of blocks.
When clicked, the target block (or group of blocks) will be extracted and attached to the mouse pointer to be moved and placed somewhere else.
Help block provides a link to the WIKI page that describes the target block. The web page opens up in a new tab and automatically positions itself to the block selected.
This is a very handy operation that places a copy of the selected block sets to the clipboard.
These then can be pasted not only within the same project, but also between different projects.
It is even possible to copy/paste between different instances of the MicroBlocks editor (browser version or stand-alone version).
This operation has a related pair, copy all scripts to clipboard, that is accessed when the scripting area background is clicked. That one copies all the scripts in the project.
This is a feature that is mainly used to incorporate MicroBlocks programs into web page compositions, since the format is URL encoded. Here is an example of the program used above:
And this is the same program saved in URL format:
While this URL save sample is of a very small program (only two blocks) and the URL version is only about a line, an actual program will be of considerable larger size and the its URL version will also be of considerable length.
Another handy operation to make an image copy of the script or block selected. The image will be saved in PNG format.
This operation has a related pair, save a picture of all scripts, that is accessed when the scripting area background is clicked. That one makes an image of all the scripts in the project.
The size of the saved image is controlled by the option set exported script size on the menu displayed when the IDE area is right-clicked.
Next step is where a system file dialog is displayed, and the user can designate the save location on their PC.
You will see this operation only if the show advanced blocks in the MicroBlocks menu is selected.
As with the other "save picture of script" block, this one makes an image copy of the script or block selected. However, before the picture is snapshot, the block / script content is executed and the result, if displayed, is included in the snapshot. Many of the examples provided in the Reference Manual are done with this option.
Here are a sequence pictures demonstrating this operation.
A system file dialog is displayed, and the user can designate the save location on their PC.
NOTE: Since this operation waits till the script execution is finished before taking the snapshop, it is NOT possible to take pictures of scripts where long or endless loops are active.
Check out this version of the example used so far.
Because there is a forever loop before the say display, the script never ends, the say message is never shown, and the save picture of script with result operation never gets to save the image.
REMEMBER: Both save operations described above work on the individual block level, as well as on a sequence of blocks, or entire scripts.
You will see this operation only if the show advanced blocks in the MicroBlocks menu is selected.
You will see this operation only if the show advanced blocks in the MicroBlocks menu is selected.
Most important part of this information is the first line, where the number of compiled bytes size is displayed. This information is important, because MicroBlocks scripts have a size limitation due to the limited micro controller memory sizes. Maximum compiled byte size for a script has to be no more than 1000 bytes.
This operation lists all occurrences of the selected block within the entire script, including custom blocks and libraries.
When items of the results list showing the occurrences is clicked, the specific program section containing the particular block will be shown and the block will blink a few times and then stop.
Two special versions of the "find" block are used in conjunction with the variables: accessors and modifiers. When a variable is right-clicked, the following menu is displayed with the find options.
This operation lists all occurrences of the variable block use within the entire script, including custom blocks and libraries.
When items of the results list showing the occurrences is clicked, the specific program section containing the particular block will be shown and the block will blink a few times and then stop.
This operation lists all occurrences of the variable block where the value is changed within the entire script, including custom blocks and libraries.
When items of the results list showing the occurrences is clicked, the specific program section containing the particular block will be shown and the block will blink a few times and then stop.
This block is used to display the contents of the custom blocks written by the users, and of any of the library blocks written in MicroBlocks. Some of the library blocks are implemented using code written at a lower level. These are not possible to display and when clicked on, will not display the option to show block definition.
It deletes the target block or script. Blocks or scripts can also be deleted by simply dragging them onto the Blocks Palette area.
Be careful, currently DELETE is very final.
The final menu a user can encounter while working in the scripting area is the one displayed when the surface is right-clicked.
When set block size is selected, a menu of block sizes will be displayed. Last blocksize selection used will be checkmarked.
Block sizes will be adjusted based on the user selection made.
Here are results of the 100% and the 250% selections.
Reverses the very last block movement completed. Edits (copy, delete, and paste) do not count as movements. Movements are basically restricted to block location changes done with a clicked mouse.
As a matter of fact, if there were no block or script movements done when the script area was right-clicked, the undrop option is not displayed in the menu.
Organizes the script segments and loose blocks on screen into a top down and left to right arrangement on the left side of the scripting area. Blocks are arranged in multiple columns determined by the width of the IDE area.
This operation cannot be undone !
This is the complementary pair of the copy to clipboard operation. While the other one only copied the target block or script, this one copies all scipts in the project.
This is a feature that is mainly used to incorporate MicroBlocks programs into web page compositions, since the format is URL encoded. Here is an example of the program used above:
And this is the same program saved in URL format:
While this URL save sample is of a very small program (only two blocks) and the URL version is only about a line, an actual program will be of considerable larger size and the its URL version will also be of considerable length.
This is the complementary version of the save picture of script operation. Instead of a single block or script, this one will make an image of all the VISIBLE scripts in the scripting area in PNG format. You can use the set block size command above to adjust block sizes, in case they do not fit the visible area.
Please note that if you have many scripts, it may not be possible to make all of them visible.
Controls the block size and resolutions of the saved scripts. The default is 200%.
In addition to the mouse and window scroll controls, keyboard arrow keys provide scrolling support while working in this area.
The first three icons present drop-down menus when clicked.
Selecting show advanced blocks make some additional blocks appear in the palette. It also enables additional features and menu options needed by more advanced users.
Graph opens a graph window used by the graph block to plot data. (For details, see the Graph block description in the reference manual.)
Connect is used to display and connect to system USB ports that have micro devices attached to them. There is alo the Open Boardie option for connecting to the virtual board Boardie.
As of the Pilot Release 1.2.52 VM 216 (Jan.2024), MicroBlocks started supporting programming activities via BLE (Bluetooth Low Energy) connection, thus enabling untethered programming (without the USB cable). This feature is currently supported on the micro:bit v2 and ESP32 boards. This capability is only available on the Pilot release mentioned above and later. It is not part of the standard release yet.
Refer to Bluetooth Details for more information.
Normally this indicator is not visible. However, as new programs / libraries are loaded to the IDE or any of the existing blocks are edited, this indicator shows the progress of synching the blocks to the attached microcontroller board. Note that while this icon is visible, you will not be able to perform any editing in the IDE, until the activity is completed.
At the rightmost end of the main menu bar are the two icons Start and Stop, that are used to control the program execution.
The TABBED sections below describe in detail all the contents and functionality of the menus.
This menu item allows the user to select one of the many languages the MicroBlocks editor is translated into. Once set, all menus, messages, and code blocks will be presented in that language. Custom... option at the bottom of the menu is used when creating translations for the editor. It allows the translator to test the newly created translation file by selecting it from the system menu and applying it. |
---|
Displays information about the MicroBlocks editor and Firmware versions.
This item enables the user to load the latest version of the firmware to the micro device attached. Depending on the conditions, a device selection menu may be presented for the user to choose from.
After the selection, different messages prompting for further actions will be displayed.
MicroBlocks supports many microcontroller boards. See Boards section for detailed information.
Here are some sample prompts for the Adafruit CLUE device:
As the firmware update proceeds, the green USB icon will be off. Upon completion of the update, the connectivity between the micro device and the USB port needs to be reestablished. See USB section.
When selected, the advanced options in the menus, as well as advanced blocks in the Block Categories will be enabled.
Once enabled, the menu item will change to hide advanced blocks.
Displays the virtual machine firmware version for the micro device.
ESP boards are a special category of boards by Espressive Corp. that feature WIFI capability. They have different technical specifications on how they can be updated. This item totally erases the board's memory content and loads the latest firmware.
A device selection menu is displayed to choose from. After the selection is made, firmware update starts. A graphic display informs of the progress.
When the update is completed, you may be asked to reestablish the USB connectivity. See USB section.
One of the niceties of the MicroBlocks editor is, that it always tries to make things simpler for the users. Since every micro device has different characteristics, features, and capabilities, MicroBlocks automatically tries to supplement the basic functionalities by loading various libraries.
Here, as an example, are two libraries loaded for the micro:bit device:
When selected, this item disables this functionality; and it is up to the user to load the required libraries.
Another SUPER feature of the MicroBlocks editor is that it will automatically load a project from the attached micro device, if there is no other project loaded into the editor. To ensure that the editor is free of any project blocks, select NEW from the File menu before using this feature.
To enable this feature, all one has to do is select this item in the menu. Once done, the editor will read the project from the device and then proceed to load it into the editor.
Here are displays from a micro:bit device, autoloading a project:
This feature enables users to share projects amongst themselves by simply plugging their devices into the PC.
If there is a program loaded in the work area, it will display a message, asking for confirmation for clearing the active project.
Upon positive confirmation, starts a clean new scripting area as shown below:
Scripting area is cleared of the previous script blocks. All user added libraries are cleared out. Depending on the micro device type and the setting of the option enable autoloading board libraries, certain libraries are loaded.
If the connect icon is not green and enable PlugShare when project empty is selected, then as soon as the USB connection is established, MicroBlocks will read and load the project from the attached micro device.
This is how previously saved projects on user's PC is loaded into the work area. In addition to the user's own projects, other sample projects in various categories can be loaded.
If there is an active project in the scripting area, a confirmation message is displayed. See File New above.
A file open dialog is presented:
First display is focused on the Examples category, where many MicroBlocks projects for different micro devices and hardware options are presented.
User's own PC directories can be reached by switching to the Computer tab selection on the left. This will present the standard system file open dialog, where one can select previously saved projects.
If the connect icon is not green and enable PlugShare when project empty is selected, then this option will be visible in the file menu. It will not be visible if the USB connectivity is established and the connect icon is green.
If there is an active project in the scripting area, a confirmation message is displayed. See File New above.
Assuming the above conditions are met, then as soon as the item is selected, a message to connect the device is displayed:
When the USB connection is established, MicroBlocks will read and load the project from the attached micro device.
In addition to the File Open command described above, there are several other ways of loading programs or individual scripts into the IDE.
As URL:
If the program was copied to the clipboard as URL and then the resulting link provided as such, the URL link can be clicked. This will result in the MicroBlocks IDE to be executed with the referenced program loaded and ready to be edited or run. Here is a link to the BLINK program.
As a script fragment from clipboard:
Any and all of the individual scripts on the IDE can be saved to the clipboard via the R-Click menu options copy to clipboard, copy to clipboard as URL, copy all scripts to clipboard, copy all scripts to clipboard as URL.
These fragments can then be PASTED into the IDE and worked on.
Here is a script fragment for the Blink script: Copy and paste it to the IDE.
GP Script
script 454 51 {
whenStarted
'[display:mbDisplayOff]'
forever {
setUserLED true
waitMillis 200
setUserLED false
waitMillis 200
}
}
As a PNG formatted image file, incorporating the program or script:
PNG files support an embedded header option, into which the body of a program or individual script can be placed. This is done by selecting R-Click enu options save picture of script, save picture of all visible scripts.
The resulting PNG files can then be drag/dropped onto the IDE. This will load the embedded program, ready to be worked on. Here is a picture of the Blink Program that embeds the actual code. Drag it to the IDE.
NOTE: All of the options above will preserve any libraries used by the programs, and will restore them upon loading.
Programs embedded in PNG images:
Some image / multimedia handling software do not always preserve the internal formatting of the PNG files. These may drop or delete the embedded header sections containing the program code, resulting in unsuccessful restoral of the programs / scripts.
Once a project is ready, it needs to be saved to the user's PC.
Selecting SAVE will display a system file dialog, where the user can give the program a name and save it to their PC.
There is no pre-configured file save location or option in MicroBlocks.
Designating the file locations on the PC is the user's responsibility.
One of the ways to save or transfer the project to another editing / publishing environment is to export it as an URL.
When this option is selected, a copy of the project in the URL format is placed into the clipboard. Below is an example of the BLINK.UBP program saved as URL:
https://microblocks.fun/run/microblocks.html#project=projectName%20%27Blink%27%0A%0Amodule%20main%0Aauthor%20unknown%0Aversion%201%200%20%0Adescription%20%27%27%0A%0Ascript%2050%2050%20%7B%0AwhenStarted%0A%27%5Bdisplay%3AmbDisplayOff%5D%27%0Aforever%20%7B%0A%20%20setUserLED%20true%0A%20%20waitMillis%20200%0A%20%20setUserLED%20false%0A%20%20waitMillis%20200%0A%7D%0A%7D%0A%0A
The URL format can be broken down into several parts:
Protocol (https): This indicates that the connection to the website is secure and encrypted.
Domain (microblocks.fun): This is the address of the website that hosts the MicroBlocks application.
Path (/run/microblocks.html): This specifies the location of a specific file within the website. In this case, it points to the "run" directory and then to the "microblocks.html" file. This file contains the core functionality of the MicroBlocks online editor.
Different MicroBlocks IDE versions (Stable Release vs Pilot Releases) have different paths for the IDE. As such, when you save in either of these environments, the generated URL will point to the version from which the program was saved.
Fragment (#project=projectName...): This part doesn't affect loading the page, but it provides additional information within the webpage itself. It's called a fragment or hash. Here's how it breaks down further:
Hidden Part: Encoded Project Data
The remaining text after #project=projectName is the encoded data related to the MicroBlocks project itself.
Saving projects in this way can result in extremely large URL strings, depending on the project's size and libraries used. At times, it may come in handy to use a URL-Shortener service. Here is the short version of the BLINK example used earlier, created via T.LY web service: https://t.ly/dtF9d (may not be permanent)
URL handling varies depending on the browser used. In addition, different document editing environments may place a limit on the URL strings used.
Maximum length of a URL in different browsers :
Most web browsers display the URL of a web page in the address bar. There is a limit on the length of the URL basing on the browser we use. Here are the details.
Google Chrome – Google Chrome allows the maximum length of the URL to be of the size 2MB (2,097,152 characters).
Mozilla Firefox – In Firefox the length of the URL can be unlimited but practically after 65,536 characters the location bar no longer displays the URL.
Edge – Edge allows the URL length to be a maximum of 2083 characters but not more than 2048 characters in the path portion of the URL.
Opera – Opera allows the URL length to be unlimited.
Safari – The maximum length of URL in Safari is 80000 characters after crossing this limit the page displays an error.
Apache(Server) – Apache allows the URL length to be a maximum of 4000 characters after which it throws an error message.
When custom blocks are created in a project, they normally will be saved as part of the user project file with an UBP extension.
If, however, it is desirable to make a library out of the custom blocks, and save and load them independently as library code (with an UBL extension), then they will need to be exported from the script and saved into a separate file.
This selection makes that happen.
It will display a dialog window, where the name of the library can be assigned and saved. The new file will have an UBL extension.
For further specific information on how to create a library, refer to the WIKI menu item: Creating A New Library.
The Connect icon is used to display a menu that lists different connectivity options supported:
When connect is clicked, a system USB port menu is shown, with a listing of all USB attached devices on the PC.
Selecting an entry and clicking Connect will establish a connection to the corresponding micro device.
Upon successful connection, the USB icon will change to one with a green circular background: .
When connect (BLE) is clicked, a system BLE port menu is shown, with a listing of all attached devices on the PC that have a BLE firmware loaded.
Note the three-letter code displayed with the MicroBlocks entry:
HAP - Paired indicates that a microcontroller with a BLE supported firmware was detected and annotated for the user. If there are more devices with a similar capability, they all would be listed here with different three-letter codes assigned.
Adobe Video
The same three-letter codes are also displayed on the micro:bit LED display upon power up. This can be used to locate the correct device with which a BLE connection will be established.
Selecting an entry and clicking Pair will establish a BLE connection to the corresponding micro device.
Upon successful connection, the USB icon will change to one with a green circular background: .
Another way you can confirm the connection status of MicroBlocks is by clicking on the browser tab for the MicroBlocks IDE. Depending on the USB or BLE connectivity established, you will see one of the two displays shown below:
It is important to pay attention to the status of this icon. MicroBlocks has a lot of internal automated processes to make the user's life easier when working in the editor. Automatic updating and synchronisation of the project code on the attached device is one of them. This is only possible when the icon is in green mode.
From time to time, for various reasons, the connection to the micro device might be severed. At these times the icon will not display the green circle. If you encounter this condition, editing of the programs should be paused and the reason for the disconnect should be investigated.
It is advisable not to develop or troubleshoot programs when the connection to the attached micro device is severed, indicated by the absence of the green circle around the USB icon.
BLE Connection Support:
BLE connectivity support is a new feature of MicroBlocks, introduced as of Pilot Release 1.2.52 VM 216 (Jan.2024).
BLE connectivity enables one to work untethered to the PC where the MicroBlocks IDE is running. Normally, your microcontroller is connected to your PC via the USB cable, which provides the power necessary, as well as enables programming activities provided by the IDE. This connection also necessitates that your microcontroller is located within cable-length of your PC.
When you connect via BLE, the idea is to jettison the USB cable connection and gain the ability to have the programmed device away from the PC. With bluetooth technology, this translates to a theoretical distance of 100m (300ft) or so. More likely, the practical distance will be somewhere around 25m (75ft). Nevertheless, that is quite far away from the PC used to program the microcontroller.
With the distance advantage gained comes a new problem: powering the microcontroller away from the PC. Without the USB cable, which provided power, one now has to use a different power source. This can be in form of a USB power-connection or a battery connected to the microcontroller. Many project kits also provide their own independent power source options.
We present several battery connectivity options below:
If you have never connected with BLE before, most likely your micro:bit firmware is not the one with support for BLE. Therefore, you need to update your firmware to the minimal release shown above. This firmware update has to happen over an USB Connection.
Once you update your micro:bit to support BLE, all your future program updates can be done via BLE connection.
Boardie is MicroBlock's new virtual board feature. Now, even without a physical board attached to the computer, it is possible to explore programming with MicroBlocks by using Boardie.
Boardie emulates:
Functionality of Block Categories supported by Boardie:
Block Category | Supported | Not Supported | ||
---|---|---|---|---|
Output | all | |||
Input | all except: |
BLE id BLE connected |
||
Pins | no | |||
Comm | no | |||
Control | all | |||
Operators | all | |||
Variables | all | |||
Data | all | |||
My Blocks | all | |||
LIBRARIES | Tone Graphics and Displays / TFT Graphics and Displays / Turtle Other/Files |
Currently, Boardie is under development and its capabilities are changing all the time. We will document Boardie fully, when it is stabilized in a release.
MicroBlocks is always live; the user can click individual blocks or scripts to run them without clicking the Start button.
The main thing the Start button does is to simulate device power-on by starting all the scripts with when started and all the when <condition> scripts.
STOP icon stops the execution of the project. All variables are deallocated. All scripts with when started and when <condition> are stopped.
The project loaded onto your micro device will be intact. In fact, you can disconnect it, power it on from an external source, and execute your project apart from the editor.
Phrase | Definition |
---|---|
Custom Blocks | A set of scripts developed by the user to achieve specific functionality. It can also be referred to as a Custom Function. |
Script | Single stack of blocks. |
Library | Specific purpose scripts provided with MicroBlocks to handle various micro device features and functionalities, as well as to enhance standard capabilities of MicroBlocks. |
Project | A combination of Scripts, Custom Blocks, and Libraries. |