Lab: Storyboard Tool

From Tekkotsu Wiki

Jump to: navigation, search

Learning Goal: This lab will introduce you to the Storyboard tool, a graphical tool for displaying state machines and their execution traces, called "storyboards".



If the Storyboard tool is not installed on your computer, see Storyboard install instructions.

Starting the Storyboard Tool

1. If you're going to be running Tekkotsu on a robot, you will need to know the robot's host name or IP address. If you're running Tekkotsu on your own computer, use localhost as the host name. To start up the Storyboard, type:

Storyboard -h hostname_or_ip_address
  • Troubleshooting tips:
    • If the result is "Command not found", you need to put /usr/local/Tekkotsu/tools/bin on your search path.
    • If the result is "Can't find storyboard executable", follow the Storyboard install instructions.
    • If you omit the -h flag or type an incorrect value for its argument, you can enter the correct value in the Host field in the Storyboard window, then click on the Reconnect button.

2. If none of the above errors occurred, the Storyboard window should come up on your display. Notice the large orange input box; this is where you will type the name of the state machine you wish to examine.

Downloading A State Machine Description

  1. Compile and run Example2 from the Lab: State Machines page. Leave the behavior running as you proceed to the next step.
  2. Start the Storyboard tool if it's not already running. Make sure to give it the correct host name or IP address.
  3. Type "Example2" into the orange box in the Storyboard window.
  4. Click on the Download Model button.
  5. When asked if you want to automatically generate a layout, click "yes".
  6. Stop the Example2 behavior in the ControllerGUI.
  • Troubleshooting tips:
    • If the Storyboard cannot connect, make sure the host name or IP address you gave it is correct.
    • If the Storyboard says that the behavior cannot be found, make sure it was spelled correctly, and that the behavior is currently running. The Storyboard cannot see behaviors that are not running.

Laying Out A State Machine

It's a good idea to put the parent state node (e.g., Example 2) in the top left corner of your layout. Put other nodes below it. In the Storyboard window's Layout panel you can click and drag on a node to move it. Or click on a node and then click and drag one of the resize handles to change the size of the node. You can also change the color and shape of a selected nodes by clicking in the Properties tab.

You can edit links as well. Click on a link and a little dot will appear in the center of the link. Click and drag this dot to move the link. Use the Properties tab to change the link color or line thickness.

Put the parent node Example2 at the top of the Layout pane. But the two other nodes below it in sequential order, with the speech node leftmost,

Click on the Save Layout button and save your layout in your ~/project directory. Call it Example2.tsl.

Generating An Execution Trace

In order to generate an execution trace, your behavior must not be running when you start the trace.

  1. Stop the Example2 behavior in the ControllerGUI.
  2. Click on the Record New Trace button in the Storyboard tool's Storyboard pane.
  3. Then start the Example2 behavior in the ControllerGUI.
  4. Generate some button press events.
  5. When you're finished, click on the Pause Trace button in the Storyboard pane to stop the logging.
  6. Click on the Save Trace As button to save your execution trace. Call the file Example2.tse and store it in ~/project.
  7. Notice that the vertical positioning of a node in the execution trace is determined by its vertical position in the layout. The horizontal positioning of a node reflects the time at which it became active.
  8. Go back to the Layout pane and try changing the vertical positioning, color, or shape of a node. Notice that the execution trace automatically adjusts to follow the layout.

A Common Mistake

If your execution trace does not show the parent state node (i.e., the Example2 node if you're following the steps in this lab), it's because you started the behavior before clicking the "Record New Trace" button. You must start recording first, and then start the behavior, in order for the Storyboard tool to see the activation of the parent state node.

Including Events in the Storyboard

You can record events, such as button presses, or audio actions (starting and stopping of sounds or speech) in the execution trace by selecting them in the Event Logger. You will learn more about this tool in Lab: Events and the Event Logger. For now, if you just want to see what events look like in the Storyboard, follow these steps:

  1. In the ControllerGUI, go to Root Control > Status Reports > Event Logger and check the boxes for audioEGID and buttonEGID.
  2. Go back to Root Control > User Behaviors and stop the Example2 behavior.
  3. In the Storyboard pane, click on the Record New Trace button.
  4. Start the Example2 behavior.
  5. Press a button on the robot, or else, in the ControllerGUI "Send Input" box, type: !post buttonEGID 0 A
  6. In the Storyboard pane, click on the Pause Trace button.
  7. Move the mouse over one of the event icons along the top edge of the execution trace and a tooltip will pop up describing that event.


  1. Solve the Combination Lock problem on the State Machine Exercises page and then lay out the statemachine graphically using the Storyboard tool.
  2. Solve the Parallel Actions problem on the State Machine Exercises page and then generate an execution trace showing the parallel structure of your solution.
  3. Solve the Concurrently Active States problem on the State Machine Exercises page and then generate an execution trace showing that the two sequences run asynchronously.