Box - Optional components¶

Parameter of a box¶

A parameter of a box is a value which enables you to slightly change the actions made by your box.

Note

You can know if a box has parameters if it has a parameter-button button displayed at the bottom-left corner of the box.

The value of the parameters can be set using the Widget to set the value of box parameters or by connecting an I/O on it.

A parameter has:

a name which has to be unique for each box, as you access the parameter value from its name in the box script.
a tooltip which is very important. Indeed, you only see the parameter name when you edit its value. So it can be useful to have this little tooltip to describe the purpose of the parameter.
an option named Inherits from parent. When this option is enabled, if there is a parent box of this box which has a parameter with the same name as this parameter, then the value of this parameter will be the value of the parameter of this parent box. Then setting the value of this parameter is useless.

Note

Even if the parent box parameter has not the same type, it is its value that is taken into account.

Also, if there is no parent box with a parameter with the same name, the value of the parameter is directly taken in to account.
a type which defines how the parameter is going to be displayed:

Type of parameters

Type

Corresponding

I/O type

Display

Boolean

Dynamic

Integer

Number

Float

Number

String

String

Attached file

String
a default value which is the original value of the parameter if you do not change it.

Widget to set the value of box parameters¶

When you click on the parameter button of a box in the flow diagram, or when you right-click on a box and select Set Parameters, the following widget is displayed:

../../../_images/chore_set_parameter_value.png

Note

If there is no parameter button on the box, it means that the box has no parameter. So you need either to add some (right-click on the box, Edit box) or choose an other box which has parameters.

The name of the parameters are on the left and their value you can set are on the right.

You can notice in the example above that you can have several types of parameters. If you want more information about these types, see the section: Parameter of a box.

There is an option Auto-update parameters on robot at the bottom of the widget. If this option is enabled, then the value of the parameters are updated during the execution of the behavior.

For example, let’s play a long song with the Play Sound box. To know how to do this, see the tutorial: Playing music. If you set the value of the Volume (%) parameter while it is playing, then it will be updated. It would not be the case if the option Auto-update parameters on robot was disabled.

You can also reset the value of all parameters to their default value by clicking on the button Reset to default.

Parameter edition widgets¶

When you create or edit a box parameter, the following widget is displayed:

../../../_images/chore_edit_parameter.png

You can here set:

the name of the parameter.
the brief description of what effect has this parameter on the box in the field Tooltip.

Note

This description will appear in a tooltip displayed by passing above the parameter value in the widget to set the value of box parameters.
the Inherits from parent option which says if the parameter value is overwritten by the parent parameter value.

You can also choose the type of the parameter and its content depending on its type:

Type	Content
Boolean	You can set the default value of the parameter (True or False). It is the original value of the parameter if you do not change it.
Integer	You can set: the default value of the parameter (value between Min value and Max value). the minimum value of the parameter. the maximum value of the parameter.
Float	You can set: the default value of the parameter (value between Min value and Max value). the minimum value of the parameter. the maximum value of the parameter.
String	You can set the default value of the parameter. You can add, edit and remove possible values of the parameter in the field Multiple Choices. Then you can set the list of possible values exclusive or not with the option Custom string possible. If this option is disabled, it is exclusive. The default value of the parameter is then the value currently displayed in the field Multiple Choices. If you did not have defined any choice in the field Multiple Choices, you can set the option Password. When this option is enabled, the value of the parameter is displayed as a password in the widget to set the value of box parameters so that each character is hidden.
Attached file	You can set the default value of the parameter (for example `/sounds/play.wav`).

For further details about these types of parameters, see the section: Parameter of a box.

How to set the value of a box parameter¶

In Choregraphe some boxes such as the Motion > Walk To box have parameters, those parameters are useful for the execution of the box and need to be set.

Parameters are accessible by the two following ways:

Click on the adjustable wrench on the bottom left corner of the box or right click on the box and click on Set parameters in the context menu.

Set the parameters and click ok.

How to add/remove inputs, outputs, parameters in a box¶

Boxes in Choregraphe can have inputs, outputs and parameters, they are useful to communicate data between boxes.

To set box parameters:

Right click on a box to get to context menu and click on Edit box.

The Edit box menu is displayed.
To edit or remove an item, select it in the list.
Click on:

button to add inputs, outputs or parameters.

This will display the Add a new input/output/parameter menu that will help you to set the properties of the input/output/parameter you are about to create.

button to remove the selected item.

button to edit the selected item.

This will display the Edit existing input/output/parameter menu that will help you to set the properties of the input/output/parameter you are editing.

Attached files of a behavior or a box¶

The attached files of a behavior (or a box) are the additional files which are needed for the execution of the behavior (or the box). For example, to execute the Tai Chi Chuan dance, you need the music that goes with it.

So in order to package the behavior (or the box) with its needed files, they can be attached to the behavior (or the box) so that they automatically come with it. To see a practical example of how to attach a file to a behavior and a box, see the tutorial: Attach a file to a behavior.

Warning

If you want to share a behavior which uses a specific image recognition database, you may wish to attach the database to the behavior so that NAO uses it during the execution of the behavior. But it is not possible for the time being as there is no available API to send a such database to the robot. The feature is coming soon but unfortunately for now you will have to:

export the database using the Video Monitor panel.
share it next to the behavior.
precise that, before executing the behavior, the image recognition database needs to be sent to the robot using the Video Monitor panel.

When you drag and drop a box which has attached files from the Box libraries panel to the What is the Flow Diagram panel, the files attached to this box are added to the files attached to the current behavior.

Warning

If a file already exists in the list of files attached to the current behavior, then the old file will be replaced by the new file.

Resource of a box¶

A resource is an element needed for executing a task (a box or a behavior). For example, to walk NAO uses the legs resource. To walk and speak at the same time, NAO uses the speech and legs resources.

You can set for each box the resources that can be used and how to manage the resources between boxes.

Managing the resources is important when exchanging behaviors for two reasons:

For resolving conflicts.

Let’s say we have two behaviors:
- One makes NAO dance on a music (Tai Chi Chuan box for example).
- The second makes NAO walk when the left bumper is pressed.
As the legs are used for the dance and the walk, the two behaviors may send contradictory commands to NAO’s legs if they both are running on NAO.
For synchronizing resources.

If your behavior makes NAO greet with the left hand and say Hello, both resources need to be available at the same time for the behavior to start.

Box Resource Edition widget¶

When you edit box resources, the following widget will be displayed:

First there is the list of the available resources. You need to select the resources that are used by your box and that you want to be only used by your box. To select or unselect a resource, click on it. To select several resources, click on the first resource. Then keep pressing on the CTRL button and click on each other resource you want to select.

Note

The list of available resources is empty when you are not connected to any robot. Then you should connect to a robot before setting box resources.

Then you can choose what happens when the *same resources are asked by another box:

Lock: The ongoing box is not stopped and does not release the resources for the other box.
Stop on demand: The ongoing box is stopped and releases the resources for the other box.
Callback on demand: The onResource function (if any) of the box script is called.

Note

This is an option for advanced users only. For more information about this kind of built-in functions, see the section: Built-in functions in the script of a box.
Pause on demand (beta): The timeline (if any) of the ongoing box is paused at the current frame. The timeline is played again as soon as the resources are released again.

You can set the time waited by the box when it is started if the required resources are already taken:

Immediate: If the resources are not immediately available, the box is immediately stopped.
Wait n seconds...: The box waits a maximum number of seconds. If the resources are released before the end of this time, then the box is started. But if they are still not available after this time, then the box is stopped.

You can set the maximum number of seconds to wait in the next field.
Infinite: The box waits infinitely until the resources are finally available.

Finally, you can make Choregraphe try to automatically detect the resources needed by the box. To do so, click on the button Detect.

Warning

This function may miss some resource you use in your box. So we advise that, after clicking on this button, you make sure yourself that every used resource is selected in the list.

How to set resources in a box¶

If you want to use the resource manager you need to set the resources used by your boxes.

Before seeing how to set the resources of a box, you may want to know a few things about the module AlResourceManager, see AlResourceManager section.

To set the resources of a box:

Right click on the box and click on Edit resources in the context menu.
In the following Resource editor menu, in the Resource list, select the resources or the group of resources you want.

If you want to set several resources, keep pressing the Ctrl key will you are selecting the resources.
Click on OK.

If you want to know how to use the resource manager, see the Using the resource manager section.

Plugin of a box¶

A box plugin adds a user interface directly on the frontage of the box. For example, if you choose the numberedit plugin then you will be able to choose a number directly from the box frontage instead of in parameters.

It automatically generates a script for the box which then will not be editable.

It can also be useful if you want to make specific commands during the edition of your behavior. For example, if you choose the ui_choice plugin then in advanced options (the + button) you will have a button to calculate the approximative recognition confidence of each word.

Note

We strongly advise you to use parameters instead of plugin as it is a very advanced feature to use.

NAO Software 1.12 documentation

Box - Optional components¶

Parameter of a box¶