MicroBlocks
MicroBlocks is a blocks language (like Scratch) that makes it easy for beginners (9 years to adults) to program DUELink boards. A huge benefit of MicroBlocks is that it is live and interactive: users can click commands to see what they do and they can test their scripts as they work.
Yet in spite of its apparent simplicity, MicroBlocks is a fast, powerful programming language with the ability to interface with peripherals via GPIO, I2C, SPI, and serial and nearly 200 extension libraries. In fact, some hardware designers prefer MicroBlocks for rapid prototyping and testing because of its fast, interactive development cycle.
There are two ways to use MicroBlocks with DUELink:
- Run MicroBlocks directly on DUELink modules/boards Standalone.
- Use MicroBlocks to control Tethered Modules.
Most product pages include Tethered and Standalone sample projects.
An example of Standalone is when loading and running MicroBlocks directly on boards like DueSTEM or Ghizzy.
A tethered example can be micro:bit that is controlling LED RGB3. The LinkBit adaptor is here to give micro:bit the needed Downlink interface.
It is also possible to combine both options! In this case, MicroBlocks will run Standalone on a DUELink board, that is also Tethered to one, or more, DUELink modules. This can for example be CincoBit running MicroBlocks firmware and user blocks Standalone that is controlling LED RGB3 module.
MicroBlocks Standalone
While you can load MicroBlocks to make any DUELink module run Standalone, the ones recommended on the educators page make it especially easy to get started.
Installing the Firmware
Educational-tailored boards automatically ship with MicroBlocks preloaded. You can skip this section in most cases. However, here are the steps needed to load MicroBlocks firmware, a process that takes less than a minute.
Start by connecting your DUELink board to a computer using a USB cable. Make sure it is not a charge-only cable!
Linux may require an extra step to ensure that the user has access to USB serial devices. See the Linux tab in the Computer Setup section of the MicroBlocks Get Started page.
The board must be placed in a special DFU (Device Firmware Update). This mode can be entered using the Erase All option found in the Firmware top-menu on console.duelink.com. The Loader page has full details if needed.
The board should now have no firmware installed and and is in DFU mode. If you are in using Windows and want to double check, you can check the Device Manager.
You also have the option to force DFU mode without erasing the firmware by holding LDR or A buttons during a module reset or power up.
The process is similar for all educational-tailored microcomputer boards. For example, prepare CincoBit to accept firmware by holding down the A button while clicking the RESET on the back of the board:
|
|
On DueSTEM, the button is labeled LDR (left-most red button). Hold it while clicking the Reset button:
ClipIt is done similarly to DueSTEM:
With your board connected in DFU mode (via Erase All or using buttons), open console.duelink.com in a Chrome or Edge browser:
Click on the Firmware tab:
In the dialog that appears, click the Connect button. You should see a dialog box with an entry marked DFU in FS Mode:
If you do not see the dialog box, make sure you are using a Chrome or Edge browser. Other browsers cannot connect to the board.
If you do not see see DFU in FS Mode, repeat the board preparation process described above. If using Windows, you can check the Device Manager as your PC may needs the DFU drivers. Download and install the USB drivers from the downloads page.
Select the DFU in FS Mode entry and click the Connect button.
In the next dialog, select MicroBlocks (microblocks.fun) in the Firmware menu. The version menu will default to the most recent version, which is what you want:
Click the Load button.
You'll see progress as the board is erased and then the firmware is written:
Close the Console browser tab. Congratulations! You've installed MicroBlocks, you're ready to start coding!
You don't need to install MicroBlocks firmware every time you use MicroBlocks, only if you want to update to a newer version or switch between MicroBlocks and DUELink firmware.
Although this section focused on installing MicroBlocks on the educational microcomputer boards, MicroBlocks can be installed on any DUELink board. See MicroBlocks Everywhere!.
Connecting the Board
You can run MicroBlocks in a Chrome or Edge browser by visiting microblocks.fun and clicking the Run button in the top bar menu or by clicking this link.
You can also download a stand-alone app for Windows, macOS, or Linux from the MicroBlocks Download page.
The first step is to connect to the board.
Linux may require an extra step to ensure that the user has access to USB serial devices. See the Linux tab in the Computer Setup section of the MicroBlocks Get Started page.
Click the Connect button in the MicroBlocks editor:
Select Connect (USB) from the menu:
Select the DUELink MicroBlocks board in the dialog that appears, then click the Connect button:
If you do not see your DUELink MicroBlocks board, make sure it is connected with a good USB cable, then click its reset button.
When the board is connected, the Connect button will turn green and the name of the board will appear next to it:
With the board connected, click the file icon and select New from the menu:
MicroBlocks will load a set of libraries that can be used with that board:
To verify that everything is working, click on the set user LED block in the Output category:
On most DUELink boards, this will turn on the green STAT LED. On the CincoBit, which does not have a STAT LED, it will turn on the middle LED in the 5x5 LED display.
Coding in MicroBlocks
MicroBlocks is a live coding environment so you can test as you code and try out blocks to discover what they do.
Click on a block or script to run it:
Drag blocks into the scripting pane and assemble them to create scripts.
Your code is stored in persistent flash memory and can run even when the board is not connected to the MicroBlocks editor.
Scripts starting with a when started block will run when the board is powered on.
MicroBlocks supports concurrency. Up to ten scripts can run at the same time.
Examples
Here is a simple script for the CincoBit:
Here is a similar script using the ClipIt's A touch pad:
These scripts will switch from a "smile" to a "frown" on the CincoBit based on the pressed button.
This script displays the light level as a bar graph on the PixoBit and DueSTEM. It also shows the temperature on the DueSTEM:
In addition to its many built-in blocks, MicroBlocks has nearly 200 libraries that support additional features and peripherals. Click the Add Library button to add libraries.
MicroBlocks Pin Numbers
On the CincoBit and PixoBit, MicroBlocks uses the same edge connector pin numbers as the micro:bit. Pins 0, 1, and 2 are the three alligator clip connections with holes on the left side of the edge connector.
On the CincoBit:
- pin 9 is the analog light sensor
- pin 21 is the buzzer
On the PixoBit:
- pin 21 is the buzzer
- pin 22 is the display reset pin
- pin 23 is the analog light sensor
On all other DUELink boards, MicroBlocks uses standard DUELink pin numbers. Pins 0-9 and 17 are capable of analog input. The pin numbers are marked on the DueSTEM and most other microcomputer boards. You can always find the pin numbers for a given board on its schematic.
Tethering Modules
MicroBlocks can control Tethered DUELink modules. It can be a single module, or a Daisylink of modules. When you do this, only the first module in the chain runs the MicroBlocks firmware. All other modules in the chain run the standard DUELink firmware and respond to commands from MicroBlocks.
Tethering Options
If you are running MicroBlocks on a DUELink board/module, connect the Downlink (D) connector on that board.
to the Uplink (U) connector of the next DUELink module.
If you are running MicroBlocks on a non-DUELink board, connect the Daisylink module chain to your board's I2C or UART pins. If you have a micro:bit, you can use a LinkBit to tether DUELink modules.
When using multiple DUELink modules, modules are daisy-chained together by connecting the Downlink (D) connector of one module to the Uplink (U) connector of the next (see Daisylink).
Always connect a Downlink (D) connector to an Uplink (U) connector. Nothing will work if a D is connected to a D or a U to a U anywhere in the chain.
Once all connections have been made, power cycle the entire chain to reset all modules before attempting to use any module.
Daisylink Library
We maintain a set of libraries to simplify the use of MicroBlocks with DUELink. DUELink Daisylink is of these libraries and it is used to access and control Tethered modules, which can be one module or a Daisylink of modules. In either case, we need this DUELink Daisylink library.
In the MicroBlocks editor, click the Add Library button:
then from Libraries select Kits and Boards and then DUELink Daisylink library:
In this example setup, CincoBit is the board running Standalone and MicroBlocks is loaded and is running on it. The tethered LED RGB3 is is running the official DUELink firmware and is controlled by commands coming from CinoBit.
From the DUELink Daisylink library palette click on the DUELink connected? block to verify that your LED RGB3 is connected and detected by CincoBit:
If DUELink connected? returned red off button you may have to click the block again, or need power cycle the entire system and try again. Modules can't be connected/disconnected live, a power cycle is needed after chain changes. If you still don't get a positive response, check your wiring.
In this Daisylink example, there is only one device, which is LED RGB3, and it is address 1. If you have another module connected downlink to LED RGB3 it will become device address 2. You can use select device block to select the desired device, and then use the DUELink connected? block again to verify that the selected device is functional.
Device address 1 is automatically selected on power up. If you only need to use device address 1, there will be no need to use the select device block.
Module Drivers
Modules that are meant to be commanded in a Daisylink, like LED RGB3 ship preloaded with DUELink official firmware andDriver Script. The driver gives you a set of functions that you can access externally, without needing to understand how the module works nor needing to look at schematics. Those functions are documented under the individual product pages, under the Driver tab.
In this case, LED RGB3 includes SetLed(i, c) function, which sets an LED at i index (0 to 2) to c a hexadecimal RRGGBB color (e.g. FF0000 is red).
The DUELink Daisylink library includes helper blocks to build these function. Here is an example of a helper block set RGB3 led that takes the 2 needed argument, the LED index and its color.
Daisylink Example
This script will sequence through the RGB3 module's LEDs with different colors when the A button is pressed:
The results will look like this:
MicroBlocks Everywhere!
We recommend starting with MicroBlocks on the boards recommended for educators. From there, all other modules can be daisylinked as shown in the previous section. However, it is possible to run MicroBlocks on any DUELink module, allowing it to run Standalone! For example, you can install MicroBlocks on the LED RGB3 and control the LEDs directly from MicroBlocks.
Since LED RGB3 does not have a USB connector, you will need an adapter such as USB Hook.
Just like before, to install MicroBlocks firmware on a board, you need to set the board in DFU mode. You can do so using the Erase All feature explained earlier. The other option was to force DFU mode using the LDR button. These boards do not have an LDR button but you can accomplish the same results by inserting a small metal paper clip (or a wire) between 2 special small pads, while powering up the board. See the Loader page for full details.
Please note, once once you have MicroBlocks firmware installed on the RGB3 module, you no longer have the DUELink firmware and module Driver Script. Controlling the module's hardware must be done 100% with MicroBlocks code. For modules with simple hardware such as LEDs, buttons, and analog sensors, the MicroBlocks code is easy to write. However, more complex modules such as displays and SD card readers are best used as Daisylinked modules so one can take advantage of the hardware support built into the DUELink standard firmware. For example, instead of loading MicroBlocks directly on the SD Card module and worrying about file system and SD drivers, use MicroBlocks firmware on CincoBit, which is then connected to the SD Card module that is running the DUELink standard firmware and Driver Script.
Additional Libraries
When connected to one of the educational boards, MicroBlocks adds the relevant libraries automatically. For example, when a new project is created while connected to a CincoBit board, MicroBlocks adds the LED Display library.
Beyond what is already included in MicroBlocks editor, we also provide additional MicroBlocks libraries. Download the library you need from the Downloads page and add it to your MicroBlocks project by using the Add Library button or by dropping the library file onto the MicroBlocks editor.
Linux Support
DUELink modules loaded with MicroBlocks firmware fully work with Linux. However, in order for MicroBlocks to work, you need to have permission to access the serial port. Linux users are expected to know how to do so but here is an example sell script to get you started.
#!/bin/bash
echo "Adding user to dialout group for serial port access..."
sudo usermod -aG dialout $USER
# Check if user was added to dialout group
if id -nG "$USER" | grep -qw "dialout"; then
echo "User $USER added to dialout group successfully."
else
echo "Failed to add user to dialout group. Please check permissions."
exit 1
fi
echo "Creating udev rule for STM32 DFU mode..."
# Add the udev rule for STM32 DFU mode (Vendor ID: 0483, Product ID: df11)
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0483", ATTR{idProduct}=="df11", MODE="0666"' | sudo tee /etc/udev/rules.d/99-stm32-dfu.rules > /dev/null
# Reload udev rules to apply the changes
sudo udevadm control --reload-rules
echo "Permissions set successfully!"
echo "For changes to take effect:"
echo "- You need to log out and log back in for the group changes (serial port access) to take effect."
echo "- After logging in again, you should have access to both serial and DFU mode without requiring sudo."
echo "If you are unsure about how to log out, please simply restart your system."
Save the above script into a .sh file and give it executable permissions (chmod +x). Now, you can run the .sh file and then reboot (or re-login), for the system to take effect.
MicroBlocks Resources
These are some useful resources: