Latest revision as of 08:30, 12 May 2014

BP Blockly User Guide

Introduction

BP in Google Blockly is an experimental platform set to illustrate visually the basic capabilities of behavioral programming.

It is implemented in Blockly by introducing new programming blocks, and by using the co-routines (generators) facility of JavaScript. Behavioral programs written in Blockly are translated into and executed as JavaScript programs.

Installation / Getting started

• Install Firefox browser version 15.0.1 or later.
• For online use: open with FireFox the designated Blockly link
• For offline/local use on your computer:
  • Download the zip file containing the Blockly and JavaScript package from the download screen;
  • Extract the zip file, preserving directory structure;
  • Open with Firefox the file BP_Code\apps\BP\index.html;
• Look at example projects in the examples drop down, additional examples linked from this site, and the tutorial

User Interface

Tabs

The BP Blockly interface introduces four tabs:

• Blocks: In this tab, on the left is the 'pallet' or menu of Blockly blocks to choose from, and on the right is the canvas where the application is developed.
• HTML: In this tab you program the HTML interfaces of your application, especially sensors and actuators.
• Project Blocks: In this tab you can define new application-specific blocks. For example, application specific events.
• JavaScript: This tab, shown in "debug" mode, shows the executable JavaScript generated from the Blockly code
• XML: This tab, shown in "debug" mode, shows the text file where the entire application is stored.

Navigation

• To scroll click and drag the canvas up or down, or use the scroll bar.
• Note that at initial loading parts of an application may be hidden and you may need to scroll up.
• Actions: Right click offers a popup menu

Programming

• To create an application drag blocks onto the canvas
• To start the application click on the red "Play" button
• To provide HTML information, look at templates of existing projects and at AGERE!2012 paper.
• Sensor example: for translating a button click into a behavioral event

input value="StartGame"
type="button"
onclick="startGame();"
style="position:relative;background-color:LightPink;"

• To create an actuator, code

when_<eventName> = ... < mycode >

• Example actuator which changes a screen display:

 input value='Status:     Playing       '
 type="button"
 when_DisplayWin ="value='Status: *** Successful*** ';alert(' !!! You Won   !!! ');"
 when_DisplayLose="value='Status: !!! Game Lost !!! ';alert(' !!! Game Lost !!! ');"
 style="position:relative;background-color:LightPink;"

• Your application is not required to have its own GUI and HTML – you can experiment with creating interwoven behavioral flow just with events
• B-thread priority:
  • Round robin: All b-threads have same priority. Events that are requested and not blocked are chosen from the different b-threads in turn.
  • Strict priority: All b-threads are ordered, as determined by their top down and left-to-right placement on the canvas (presently disabled).
• Loading an existing project: Click "Load project", and browse and select an XML file where a project has been saved.
• Saving a project: Click "Save Project" and use standard browser functions to save the XML file. Close the extra tabs.
• Debugging and Event Logging:
  • Use Firefox console native, or
  • Use [ http://getfirebug.com/ Firebug tool]:
    • Start the application
    • In the application GUI screen – click on the firebug icon;
    • You may have to reload the application GUI screen;
    • In the firebug display click console tab;
    • In the console drop-down - make sure console is enabled;
    • Start the application
    • Watch the events in the console log.
• Do not edit the compiled JavaScript or XML file;
• Avoid spaces or periods in strings and variable names
• Sometimes the XML file may be corrupted. To avoid losing your data, save frequently in different file names and verify the file can be loaded.

BP Programming Blocks

With BP you have in Blockly the following new programming blocks:

• B-thread: In the version of BP for Blockly there is no separate block for behavior threads. Each contiguous set of execution blocks forms a b-thread. You can add a comment to the b-thread, indicating its name or function, but this is not mandatory. An earlier version of BP there is a container block for a b-threads.
  • However, the block called "instantiate with" enables the creation of multiple b-threads with different parameters. See example in the Tic-Tac-Toe game.
• Event: Defines a e behavioral event. The event name should be entered a string inside this event block.
• Request <event>: Request an event. The event is requested and the program continues when the event is triggered.
• Wait for <event >: wait for and event. The program continues when the event is triggered.
• Blocking <event>: This container block, forbids the specified event until the code contained in it completes
• Break upon <event>: This container block executes the code contained in it, but the execution is interrupted if and when the specified event is triggered.
• b-Sync: This block is available in an earlier version of BP for Blockly, and it can specify requested, waited-for and blocked events.
• Application specific blocks: These blocks are defined by the user in the application blocks tab, and can then be used from the pallet. They can be used for events, lists and more. For example, to code an application event block, the easiest way is to copy and paste the following code changing the text "MYEVENT" to your event name (in four places).

custom.bp_event_MYEVENT = {
  helpUrl: 'http://www.example.com/',
  init: function() {
    this.setColour(290);
    this.appendDummyInput()
        .appendTitle("MYEVENT");
    this.setOutput(true, 'event');
    this.setTooltip();
  }
};
Blockly.JavaScript.bp_event_MYEVENT = function () {
    return ['"MYEVENT"', Blockly.JavaScript.ORDER_NONE];
};

Example: Alternating Taps

• When in BP for Blockly (under FireFox), click the drop-down menu and select "Hot and Cold".

This example contains three enabled b-threads and one disabled b-thread.

• 1. Requesting the event addHot 10 times.
• 2. Requesting the event addCold 10 times.
• 3. Forcing the alternation of the two events by waiting for two occurrences of addHot event and blocking the addCold, and vice versa, in a loop.

Experimenting:

• Try disabling the third b-thread. Both remaining b-threads will run and events will alternate, per the round robin scheduling in this version of BP for Blockly.
• Then try disabling the first b-thread. Only addCold events will be triggered.
• Then enable the third b-thread, and run the program again. No events will be triggered due the blocking of addCold.
• Click on the HTML tab and examine the HTML actuator code that displays the event text upon triggering of the events. In another implementation this code could call a JavaScript method that actually opens a water tap for a few seconds.
• The 4th b-thread was loaded disabled. This is an "actuator" b-thread that reacts to the addHot and addCold events. In this case, by displaying a window with the event text. Again, this b-thread could call a JavaScript method that performs a desired action.

Example: The Rocket Landing Game Example

• Download the zipped version of BP Blockly.
• To load this example click "Load Project" and browse and select bp_code/apps/bp/examples/RocketLanding.xml.

In this game the player attempts to land a rocket on a landing pad on the surface of a planet. The rocket moves downward at a fixed speed in the vertical direction. Using GUI buttons, the player can move the rocket north, south, east and west, with the goal of positioning it directly above the landing pad. The player can also press an Up button to create an exhaust burst that suspends the rocket and prevents it from going down in the next time unit. The landing pad keeps moving on the ground either randomly or subject to an unknown plan. Four walls mark the sides of the playing area, and the rocket cannot move past them (but does not crash when it touches them). The game is won when the rocket lands exactly on the landing pad, and is lost when it touches the ground without being fully on the pad. The rocket movement is in three dimensions and the view of the entire game scene can be manipulated (tilt, pan, etc.) in 3D.

Sensor Events

• BtnEast: User clicked East
• BtnWest: User clicked West
• BtnNorth: User clicked North
• BtnSouth: User clicked South
• TimeTick: A unit of time passed
• RocketTouchedEastWall: Rocket arrived at east wall
• RocketAwayFromEastWall: Rocket departed from east wall
• (Same for west, north and south) . . .
• TouchDown: Rocket touched launch pad and is aligned with it
• Missed: Rocket reached or passed launch pad without being aligned with it

Actuator Events

• RocketWest: Request to redraw rocket 10 pixels further to the west
• RocketEast: Request to redraw rocket 10 pixels further to the east
• RocketNorth: Request to redraw rocket 10 pixels further to the north
• RocketSouth: Request to redraw rocket 10 pixels further to the south
• RocketDown: Request to redraw rocket 10 pixels down
• PadWest: The application wishes the pad to move 10 pixels further to the west
• PadEast: The application wishes the pad to move 10 pixels further to the east
• PadNorth: The application wishes the pad to move 10 pixels further to the north
• PadSouth: The application wishes the pad to move 10 pixels further to the south
• DisplayWin: The application determined that the player won
• DisplayLose: The application determined that the player lost
• GameOver: The application determined that the game should be stopped

The B-threads

The b-threads in the application can be seen on the canvas. They react to:

• User pressing a button - request rocket move
• Time ticks - Rocket descending
• Time ticks - Landing pad moves
• Rocket reaching a wall - block movements
• Rocket departing from a wall - allow movements
• Rocket touching the ground - loss
• Rocket landing on the landing pad - win
• Etc.

A key point to observe is that the behavior when rocket reaches the walls is independent and is by blocking of a move past the wall.

Additional Examples

The dropdown menu provides two additional examples

• A nullification game: See explanation in AGERE 2012 paper
• A basic game of Tic-Tac-Toe: This example, with very basic strategies, demonstrates the instantiation of a b-thread according to a parameter list. For example, the application block "all Squares" represents a list of all possible squares, and a b-thread is instantiated for each one of these, waiting for a user click in this square, and requesting an X event in the same square.