Adding new Blocks to the Lab

This page is a Work in progress This Text describes how to add new Blocks to the open-roberta lab.

Working with Blockly

Setup and Workflow

Information on how to set up Blockly and work with it is explained here

Adding Messages

Most text in the lab that's supposed to be translatable is added through Blockly Messages

To add a new message, do the following:

1. add it to robMessages.js in /robMsg you can look at other Messages as an orientation
2. if you are fluent in German or other languages also add it to the related .json file in robMsg/json, the name has to be identical.
3. Build Blockly

• never add a message to the msg directory, you will find your messages there once you have added them and built Blockly

Testing

While making your new blocks, you should be constantly testing. To do that without constantly switching between repositories, you can use a "playground". Most robots already have a working playground in which you can test blocks intended for that specific robot, you can find them in blockly/tests/. If you need to test configuration blocks you should use a programConfiguration Playground like programConfiguration_playground_mbed.html.

Once you made a block you can add it to your playground's HTML and test it by opening it in a browser of your choice.

You can see the generated XML in the playground by typing Blockly.Xml.workspaceToDom(Blockly.getMainWorkspace()) into your browsers console.

Testing different languages: You can change the language of your playground by swapping <script src="../msg/js/_.js"></script> with the msg.js file of your choice, or robMessages.js for English

If Your Blocks Are For a New Robot/Plugin

You should start by making your playground.

• copy an already existing playground that seems most similar to what you are trying to add
• modify it to your needs
  • look for setDevice and replace the robot name and group with yours
  • remove blocks from the categories TOOLBOX_SENSOR,TOOLBOX_ACTION in <toolbox_set id="toolbox-Program"... and <toolbox_set id="toolbox-Configuration"..., this is where you add your new blocks.

---

Adding Configuration Blocks

If you want to add a simple sensor/actor to your configuration, go to blockly/blocks/robConfigDefinitions.js

First, check if that sensor already exists for a different robot

• if not you can add it by adding:
  • confBlocks.yourblock = {};
  • confBlocks.yourblock.yourRobot = { title: 'YOURBLOCK', };
    • "yourblock" should not have uppercase letters
  • a new message with the name of your robot titled: Blockly.Msg.SENSOR_TITLE or Blockly.Msg.ACTION_TITLE
  • a message for the tooltip of your sensor titled: Blockly.Msg.TITLE_TOOLTIP

If that sensor already exists, but you want to change the name or tooltip of it, you can do that by adding a new message titled: Blockly.Msg.SENSOR_YOURBLOCK_YOURROBOT or Blockly.Msg.YOURBLOCK_TOOLTIP_YOURROBOT

When adding a new configuration block through the generator, you have the following options:

• title: name of your sensor when others want to reference it
• sensor: true or false, depending on whether your block is a sensor
• inbuilt: this boolean decides if your block should have a visible name that can be changed or not
• ports: the ports of your block
• pins: dropdown menu of pins your ports can connect to
• inputs: additional input fields the user can type in
• fixedPorts: ports that can't be changed by the user
• brick: adds a field connected to blocks with the getVarDecl function

If the block you are trying to add is more complex than possible with these variables or for the older version of the configuration, you can make a fully custom block in robBrick.js. Be aware though that the name of your block actually changes how it is displayed. For example, all generated configuration blocks start with robConf_ so if your block is supposed to behave similarly, it should also start with robConf_.

When writing a custom block, you can look at other already implemented blocks or the Blockly guide

Adding Program Blocks

Adding Sensor Blocks

If you have a simple sensor block with an output, use its generator by adding it to the class robSensorDefinitions.js This is very similar to adding configuration blocks but with a few different options.

• title: name of program block
• ports: sensors the user can choose from, or 'CONFIGURATION' if It's supposed to be synced with config blocks that have the same title
• slots: adds a drop-down menu used if a sensor has multiple options for the same type of output, e.g. sides
  • you can also make slots that depend on the port chosen you can use sensors.touch.nao as a reference
• modes: modes of your sensor corresponding to its output

Every block created using the generator also needs these messages added, title being the title you chose for that block:

• Blockly.Msg.SENSOR_TITLE
• TITLE_GETSAMPLE_TOOLTIP
  • if you want a message specific to your robot add _YOURROBOT

When adding Sensors to a robot's toolbox through this method, also add it to var sensorsAll in robSensorsDefiniton.js of that robot

You can access your newly created block through the name robSensors_yoursensor_getSample

Adding Action Blocks

Most action blocks can be found in robActions.js and robActionsNewConfig.js if they are related to sensors, you can find them in robSensors.js

You can use these blocks as an orientation a few hints are:

• If you are using a new config and want the block to be connected to a configuration block you will need to add:

var dropDownPorts = getConfigPorts('relay');
this.dependConfig = {
    'type' : 'relay',
    'dropDown' : dropDownPorts
};

and .appendField(dropDownPorts, 'ACTORPORT') where you want the name of the connected actor to be shown

• If you want that connection but also want to hide the name of the configuration block because it's inbuilt add: hidePortIfOnlyInbuilt(this);
• you can check what robot is using the block with this.workspace.device
  • a lot of blocks can be reused by adding your own robot name to it

Making the block available in the backend:

WIP