Pepper Tutorial <2>: Box manipulation

In Pepper Tutorial <1>, we made Pepper say "Hello" by connecting boxes using Choregraphe.

In this tutorial, we will explain about the boxes in more detail through the use of some examples on Choregraphe.


Box Structure

Boxes are the building blocks of the application behaviour, and they are the parts that represent various functionalities with different levels of complexity.

Boxes can be found and used from the Box libraries, and users may also define their own original boxes or import from external sources that someone else has created into the Box libraries.

  1. Box name

  2. Box icon

  3. Box description: appears when cursor is on the box

  4. Inputs: connectors for receiving signals to start or stop the box or some other data

  5. Output: connector for sending the data or stop signal

  6. Parameter button: for modifying box settings


Input and Output

There are different types of inputs and outputs.

Types defined by icons

Each input and output has an associated icon displayed with it.


[onStart] The box is on start state when the signal is sent to this input. The behaviour of the start state varies depending on the type of box.

[onStop] The box is on stop state when the signal is sent to this input.

[onEvenet] Input other than Start or Stop. The box state stimulated by the input signal varies depending on the type of box.


[onStopped] When the signal is sent from this output, it indicates that the box has stopped.

[punctual] The signal from this output indicates different things depending on the type of box.

Types defined by colours

Each input and output has an associated colour displayed with it. Colours indicate the kind of data it receives or sends.

[Bang] Simple event. There is no data involvement with these inputs/outputs.

[Number] Number data (float or integer) is received/sent with these inputs/outputs.

[String] String (word) data is received/sent with these inputs/outputs.

[Dynamic] Data with either no value (Bang) or some sort of value. If there is a value, it could be one of Number value, String value, Number array, or String array.



Each box's variables can be checked and modified by clicking the parameter button found at the left bottom corner of the box.

When you click the parameter button, the dialog box that looks something like this comes up:

The modifiable variables differ by boxes. We will explain about the variables in more detail later in the tutorial.


Box contents

There are four types of boxes which vary by how they are constructed.

  1. Python box: boxes that are written with python.

  2. Flow diagram box: when some boxes and their combinations of connections are compiled to make a new box, it is called a flow diagram box.

  3. Dialog box: boxes that are written with QiChat script which is a script language that defines a conversation with Pepper

  4. Timeline box: boxes that are aligned to represent certain poses or flow based on a single timeline

In this tutorial, we will explain about Flow diagram boxes and Timeline boxes. Python boxes and Dialog boxes will be explained in a different tutorial.


Types of Box libraries

There are several categories in default box libraries.

  • standard ... box group with basic functionalities

  • advanced ... box group used for more advanced functionalities

  • tablet ... special box group used for robots with a tablet (like Pepper)

In this tutorial, we will only be using standard box group to explain what we can do with boxes.


Constructing a flow

We will explain about different kinds of boxes, and ways of connecting boxes through constructing a sample flow. We will also be explaining how to simulate a flow using a virtual robot without connecting to an actual robot hardware.

Execution order

By connecting multiple boxes in order, processing operation moves from one box to another.

In this tutorial, we will make Pepper move forward and then say "Hello".

Connecting boxes

1. Prepare the boxes that will be used.

Drag & drop following boxes from the Box libraries onto the flow diagram.

  • Movement > Navigation > Move To

  • Speech > Speech Settings > Set Language

  • Speech > Creation > Say

Boxes in Box libraries are organised by their types and seperated into different folders.

2. Connect boxes in order.

By connecting from onStart to onStopped in the order that you want the boxes to run, the Execution order is now set to Start of application > Start of Move To box > End of Move To box > Start of Say box

3. Set Language:

Click on the Parameter button, make sure that the Language is set to English, then click [OK].

4. Set the movement distance:

Movement distance can be modified in the parameter of Move To box.

Click on the Parameter button, set the Distance X as 0.2 (m), then click [OK].

Simulating flow with a virtual robot

1. Go to the "Connection" menu and click "Connect to virtual robot".

Virtual robot should be displayed on the "Robot view" pane.

The robot view perspective can be modified with dragging a mouse (both right and left clicks)

2. Go to the "View" menu and click on "Dialog" to display the Dialog pane.

3. Click on the "Upload to the robot and play" button on the tool bar.

If Pepper (virtual robot displayed on Robot view pane) moves forward and then the word "Hello" is displayed both on the Robot view pane and Dialog pane then the application is running successfully.

You may run the application with Pepper hardware instead of virtual robot by connecting Choregraphe with your Pepper and click "Upload to the robot and play".

To connect Choregraphe with Pepper, view Tutorial 1 for more detail.

Parallel execution

Multiple boxes may be executed at the same time by sending a branching signal into multiple onStart inputs.

In this tutorial, we will be explaining how to make Pepper do shake arms and say "Yay" 3 seconds after the motion starts.

1. Prepare the boxes that will be used.

Drag & drop following boxes from the Box libraries onto the flow diagram.

  • Animation > Moods > Positive > Pepper > Excited

  • Programming > Time > Wait

  • Speech > Creation > Say

  • Programming > Logic > Wait for Signals

Wait for Signals box is only executed when it receives signals from both Excited and Say boxes.

2. Connect boxes in order.

Connect to the onStart inputs of Excited and Wait boxes from the onStart of the flow diagram. This will start the Excited and Wait boxes at the same time.

Then connect the output of Wait box to the input of Say box.

Finally, connect the outputs of Excited and Say boxes to the inputs of Wait for Signals box, and end the behaviour with onStopped.

3. Customise the parameters.

Set the Timeout variable of Wait box to 3 (s), and set the Text variable of Say box to "Yay".

4. Simulate the behaviour with a virtual robot just like the one before.

Customise motions

Excited box is in a Timeline Box format, in which motions and behaviours are combined based on time frames. Let's customise this timeline to modify the timing of Excited motion.

1. Double click on Excited box

2. The timeline pane that looks like the picture below will appear.

  • The timeline represents the Time progress of the change in motions. The grey boxes on the timeline is called the "motion key frame", and each holds a record of Pepper's motion at a particular timing.

  • The unit of a timeline is a "frame", and the number of frames per second to execute can be customised in the "Timeline properties". (25 frames/s by default)

  • "Behavior layers" is used when setting certain behaviours to play along with a timeline.

3. Select a part of the timeline with a left click mouse drag [A], and drag the right corner of the selected area [B] to expand the timeline.

4. Select a part of the timeline [A] and drag the left corner of the selected area [B] to shift the timeline.

5. The areas where key frames are positioned can also be selected, and be copied and pasted as well.