Sunday, June 17, 2012

How to add user defined blocks!

We are working on the new Minibloq's Developers Guide (which is still under construction). Here is a fragment of that guide, which describes the basics of writing new blocks for Minibloq:

Minibloq loads the blocks at runtime. All the blocks are defined in XML files. In the future, we plan to document better how to add custom blocks. Also, the block syntax will still evolve (there is still a lot of work to do). But even now, it's possible for the users to write their own custom blocks. Although we are working hard in Minibloq's documentation, by now, we can give here just an example. There is also a nice tutorial in the forum, written by Andrew Lawrance, with more complex explanations about this topic. So here is the example:

Example: Adding a delayMicroseconds() block
Let's add a new block to use the delayMicroseconds() function from the Arduino API. To do this, we will start from a block that already exists. This block is very similar to the one we want to create: It's the delay block. So we just need to follow these small steps:
  1. Make a copy of the  folder which belongs to the delay block  (you will find it in the Components\Minibloq\Lib\CPP\Blocks subfolder, inside Minibloq's installation path). The delay block folder's name is action.010.0040.delay.Arduino.v1.0
  2. Rename the new folder. For example, this may be a good name:  action.010.0050.delay_us.Arduino.v1.0
  3. Inside that folder, you will find the file main.block. Open it with a raw editor (like Notepad++, for example).
  4. Change the following line:
     delay

    by this:
     delayMicroseconds
  5. Now change this another line (and then save the file):
     delay

    by this:
     delayMicroseconds
  6. Now you have to tell Minibloq which boards will load this block when they are selected (every block can be compatible or incompatible with a board, and is the Developer's task to decide this). For this, you will need to create an empty  txt file (in future versions these files will have some content, but right now they are just empty raw text files) named with the same name as the folder where you created the new block, followed by the .rel extension. In our example, this file will be named action.010.0050.delay_ms.Arduino.v1.0.rel
  7. Copy that file to the Matrix subdirectories of all the boards (or targets) that you want to load that block. For example, to add the block to the Arduino Uno board, you will need to copy that file in the  following subdirectory (inside Minibloq's installation path): Components\Minibloq\Lib\CPP\Targets\ArduinoUNO_Arduino.v1.0\Matrix
  8. Now select your board. If you have already selected it, just press the Reload blocks button in the Hardware window (this window can be made visible with the menu View->Hardware). Your Actions picker must be something like this (please note the two "delay" blocks):
Note that we did not change the block's images (for the block itself, or for the picker), nor the structure of the block (regarding parameters, for example). Even the tooltip was untouched. This is just a very basic example, now you can dig into the XML structure of the blocks, and as Minibloq does not require to reinitialize the application, you can quickly see the changes of your block using the Reload blocks button. We will improve the blocks' XML documentation when the syntax becomes more finished, but by the moment, we encourage you to take a look to the XML definitions of more complex blocks, such as the while block (in the action.010.0010.while.CPP.v1.0 subdir), the buzzer (action.020.0050.Buzzer.Arduino.v1.0) or the Motor block (action.020.0060.Motor.Arduino.v1.0).