Custom Blockly Blocks are easily created using the Block Factory. Since we have complete control over the Python translation for a custom block, we can pretty much create a block to do anything you want.

Coderbot includes some custom blocks for controlling and accessing the raspberry pi camera, and driving pwm outputs for servos or motors. The definition for these blocks is in blocks.js

Note that a custom block has two important javascript components to it: the block definition (Blockly.Blocks['group_function']) that defines the block interface, color, etc. and the block code translation (Blockly.Python['group_function']) which returns the Python code translation for that block. The scope of the translated Python code seems to be the same as program.py i.e. any libraries and functions available this file are also available to any translated python code.

In this example we look at how coderbot custom blocks are implemented.

This first statement is the block definition in JavaScript and includes block formatting information, labels, and other things that are covered in the Blockly documentation.

Blockly.Blocks['coderbot_armRaise'] = {
  /**
     * Block for armRaise function.
     * @this Blockly.Block
     */
  init: function() {
    this.setHelpUrl(Blockly.Msg.CODERBOT_ARM_RAISE_HELPURL);
    this.setColour(290);
    var di = this.appendDummyInput()    
    if (CODERBOT_PROG_LEVEL.indexOf("basic")>=0) {
      di.appendField(new Blockly.FieldImage('/images/blocks/arm_raise.png', 32, 32, '*'));
    } else {
      di.appendField(Blockly.Msg.CODERBOT_ARM_RAISE)
    }
    this.setPreviousStatement(true);
    this.setNextStatement(true);
    this.setTooltip('Coderbot_armRaiseTooltip');
  }
};

The Blockly.Msg variables above are initialised in bot_en.js or en.js. They're localisation strings so that this program can be easily translated for users that speak different languages (also see bot_it.js and it.js).

Blockly.JavaScript['coderbot_armRaise'] = function(block) {
  // Generate JavaScript for raising the arm
  return 'get_bot().servo3(' + CODERBOT_ARM_ANGLE_RAISED + ');\n';
};

Blockly.Python['coderbot_armRaise'] = function(block) {
  // Generate Python code for raising the arm
  return 'get_bot().servo3(' + CODERBOT_ARM_ANGLE_RAISED + ')\n';
};

In the code translation for coderbot_armRaise there is reference to CODERBOT_ARM_ANGLE_RAISED which is a variable whose value is set in the config_params.html webpage template. At runtime the template values are replaced with config values which are stored in coderbot.cfg. The config file coderbot.cfg is automatically generated from the form in config.hmtl. This means that any variable whose value is stored in this file must also be derived from the HTML form in config.html. See this wiki page for detail on config.html and coderbot.cfg

The layout of the library of blocks is defined in a number of XML files like coderbot_std.xml. Each XML file corresponds to a different 'coderbot runlevel' which basically restricts the library of blocks displayed based on a setting in coderbot.cfg. The arm raise and lower blocks feature in all of these XML files.

1 - Make block using the Block Factory.

2 - Copy The Javascript Block code and the Javascript and python Generator Stub onto the end of static/js/blockly.js

3 - Edit the var code to call a python function. get_bot() returns coderbot.py, get_cam() return camera.py etc... Note that the function in the python version does not have a semi-colon at the end

4 - Add the new function in the corresponding python file

5 - Add Block to the Blocks_X.xml run level files, where X is currently adv,basic,basic_move and std. (We plan on changing these run levels)