Revision as of 14:38, 28 April 2014

BP Blockly User Guide

Introduction

BP is implemented in Google 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:

• 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.
• Application specific events: These events are defined by the user in the application blocks tab, and can then be used from the pallet. To code an application block. The easiest way is to copy and paste the following code changing the text "MYEEVENT" to your event name (4 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];
};

Examples

The dropdown menu provides three examples

• A water tap example with two b-threads adding hot water and cold water separately, and a third one alternating between them.
• A nullification game
• A basic game of Tic-Tac-Toe

Two additional examples are provided in the examples folder. To load them, press Load Project, and then go to the folder where you have downloaded BP Blockly, and browse the subfolder ..BP_Code/apps/BP/examples.

• WaterTap2.xml - A similar example to the hot cold example above, with an actuator b-threads that prints a message
• RocketLanding.xml - A 3-dimensional rocket-landing game, explained in more detail below

The Rocket Landing Game Example

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
• . . .
• TimeTick: A unit of time passed (s
• RocketTouchedEastWall: Rocket arrived at east wall
• RocketAwayFromEastWall: Rocket departed from east wall
• . . .
• 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
• RocketDown: Request to redraw rocket 10 pixels down
• PadWest: The application wishes the pad to move 10 pixels further to the west
• . . .
• 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.