SimRobot¶

The B-Human software package uses the physical robotics simulator SimRobot¹² as front end for software development. The simulator is not only used for working with simulated robots, but it also functions as graphical user interface for replaying log files and connecting to physical robots via Ethernet or Wi-Fi.

Architecture¶

Four dynamic libraries are created when SimRobot is built. These are SimulatedNao, SimRobotCore2, SimRobotCore2D and SimRobotEditor³.

SimRobotCore2 is the simulation core. It is the most important part of the SimRobot application, because it models the robots and the environment, simulates sensor readings, and executes commands given by the controller or the user. The core is platform-independent and it is connected to a user interface and a controller via a well-defined interface.

SimRobotCore2D is a simulation core for 2D simulations. It has the same role as SimRobotCore2 and is selected based on the suffix of the loaded scene filename (.ros2d instead of .ros2).

SimRobotCommon is a static library which contains code shared by SimRobotCore2 and SimRobotCore2D.

The library SimulatedNao is in fact the controller. It links against the object library B-Human that contains the framework, modules and representations. In the scene files, this library is referenced by the controller attribute within the Scene element.

The following graph shows the most important parts of SimRobot (excluding third-party libraries). Rectangles represent projects that create the corresponding library or executable. Dynamic libraries are represented as rectangles with rounded sides. Static libraries are depicted as rectangles with rounded corners. Solid arrows mean "creates". Dotted ones mean "used by".

graph LR
    SimRobot[SimRobot]
    SimRobotExecuteable{SimRobot App}
    libSimRobotCore2([libSimRobotCore2])
    libSimRobotCore2D([libSimRobotCore2D])
    libSimRobotEditor([libSimRobotEditor])
    libSimRobotCommon(libSimRobotCommon)
    libSimulatedNao([libSimulatedNao])
    sceneDescription{{sceneDescription}}
    SimulatedNao[SimulatedNao]
    SimRobotEditor[SimRobotEditor]
    SimRobotCommon[SimRobotCommon]
    SimRobotCore2[SimRobotCore2]
    SimRobotCore2D[SimRobotCore2D]

    SimRobot-->SimRobotExecuteable
    libSimRobotCore2-. "*.ros2" .->sceneDescription
    libSimRobotCore2D-. "*.ros2d" .->sceneDescription
    libSimulatedNao-. "#60;"Scene controller=<br>''SimulatedNao''> .->sceneDescription
    sceneDescription-.->SimRobotExecuteable
    libSimRobotEditor-.->SimRobotExecuteable
    SimulatedNao-->libSimulatedNao
    SimRobotEditor-->libSimRobotEditor
    SimRobotCommon-->libSimRobotCommon
    SimRobotCore2-->libSimRobotCore2
    libSimRobotCommon-.->libSimRobotCore2
    libSimRobotCommon-.->libSimRobotCore2D
    SimRobotCore2D-->libSimRobotCore2D

B-Human Toolbar¶

The B-Human toolbar is part of the general SimRobot toolbar which can be found at the top of the application window. It allows setting the representations MotionRequest and HeadAngleRequest to frequently used values.

Button	Function
	Lets the robot stand up.
	Lets the robot sit down.
	Allows moving the robot's head by hand.

Scene View¶

The scene view (e.g. the central view in the image below) appears if the scene is opened from the scene graph, e.g. by double-clicking on the entry RoboCup. The view can be translated by dragging, rotated by dragging with the Shift key pressed, zoomed, and it supports several mouse operations on objects:

• Left-clicking an object allows dragging it to another position. Robots and the ball can be moved in that way.
• Left-clicking while pressing the Shift key allows rotating objects around their centers. The axes of the rotating objects can be selected first by pressing the x, y or z key, before pressing and holding the Shift key.
• Double-clicking an active robot selects it. Robots are active if they are defined in the compound robots in the scene description file (cf. this section). Robot console commands are sent to the selected robot only (see also the command robot).

The following image shows SimRobot running on Linux, Windows, and macOS. The left pane shows the scene graph, the center pane shows a scene view, and on the right there are two views showing the images of both cameras. The console window is shown at the bottom.

Information Views¶

In the simulator, information views are used to display debugging output such as debug drawings. Such output is generated by the robot control program, and it is sent to the simulator via message queues (this section). The views are interactively created using the console window, or they are defined in a script file. Since SimRobot is able to simulate more than a single robot, the views are instantiated separately for each robot. There are 11 kinds of information views, which can be selected from the scene graph (cf. the left widget in the previous image).

Image Views¶

An image view displays debug information in the coordinate system of the camera image. It is created using the command vi (cf. this section). The background of an image view can either be empty, a regular camera image (optionally JPEG-compressed to reduce the bandwidth needed), or any debug image sent using the SEND_DEBUG_IMAGE macro. In addition, all image views created by the standard startup scripts have the feature that clicking inside them while holding the Shift key moves the robot's head to make the clicked point the center of the image. The console command vid adds debug drawings to an image view. For instance, a view of the lower image with detected ball, lines and obstacles can be created with the following commands:

for Lower vi image lowerImage
vid lowerImage representation:BallPercept:image
vid lowerImage representation:LinesPercept:image
vid lowerImage representation:ObstaclesImagePercept:image

To remove a debug drawing from a view, the off option can be appended to a vid command.

Color Space Views¶

Color space views visualize image information in 3-D. They can be rotated by clicking into them with the left mouse button and dragging the mouse afterwards. There are two kinds of color space views:

• Image Color Channel: This view displays an image while using a certain color channel as height information (cf. the image above).

• Image Color Space: This view displays the distribution of all pixels of an image in a certain color space (HSI, RGB, or YCbCr). It can be displayed by selecting the entry all for a certain color space in the scene graph (cf. the image on the right).

Each image view with a background image also has color space views as children in the scene graph.

Field Views¶

A field view displays information in the system of coordinates of the soccer field. The commands to create and manipulate it are defined similar to the ones for image views. For instance, the view worldState is defined as:

# field views
vf worldState
vfd worldState fieldLines
vfd worldState goalFrame
vfd worldState fieldPolygons
vfd worldState representation:RobotPose
# ...

# views relative to robot
vfd worldState cognition:RobotPose
vfd worldState representation:BallModel:endPosition
# ...

# back to global coordinates
vfd worldState cognition:Reset

Please note that some drawings are relative to the robot rather than relative to the field. Therefore, special drawings exist that change the system of coordinates for all drawings added afterwards, until the system of coordinates is changed again.

The field can be zoomed in or out by using the mouse wheel, touch gestures, or the page up/down buttons. It can also be dragged around with the left mouse button or by touch gestures. Double clicking the view resets it to its initial position and scale.

Behavior View¶

The behavior view shows all currently active options and skills and the states they are in. To be able to display its contents, the following debug request must be sent (which is, however, already part of all startup scripts):

dr representation:ActivationGraph

Joint Data View ¶

The joint data view displays all the joint data taken by the robot, e.g. requested and measured joint angles, temperatures, and loads. To display this information, the following debug requests must be sent (which are, however, already part of all startup scripts):

dr representation:JointRequest
dr representation:JointSensorData

Module Views¶

Since all the information about the current module configuration can be requested from the robot control program, it is possible to generate a visual representation automatically. The graphs, such as the one that is shown above, are generated by the program dot from the Graphviz package⁴. Modules are displayed as yellow rectangles and representations are shown as blue ellipses. Representations that are received from another thread are displayed in orange and have a dashed border. If they are missing completely due to a wrong module configuration or because they are alias representations, both label and border are displayed in red. There is a module view per thread.

The module graph can be zoomed in or out by using the mouse wheel, touch gestures, or the page up/down buttons. It can also be dragged around with the left mouse button or by touch gestures.

Plot Views¶

Plot views allow plotting data sent from the robot control program through the macro PLOT. They keep a history of the values sent, up to a defined size. Several plots can be displayed in the same plot view in different colors. A plot view is defined by giving it a name using the console command vp and by adding plots to the view using the command vpd (cf. this section). For instance, the view on the right was defined as:

vp orientationX 200 -10 10
vpd orientationX representation:InertialData:angle:x

Timing Views¶

The timing view displays statistics about all currently active stopwatches in a thread. It shows the minimum, maximum, and average runtime of each stopwatch in milliseconds as well as the average frequency of the thread. All statistics sum up the last 100 invocations of the stopwatch. Timing data is transferred to the PC using debug requests. By default the timing data is not sent to the PC. Execute the console command dr timing to activate sending timing data.

Data Views¶

SimRobot offers two console commands (get and set) to view or edit anything that the robot exposes using the MODIFY macro. While those commands are sufficient to occasionally change some variables, observing data over a longer period of time or changing fields in complex structures can become cumbersome with them. For this reason, data views exist. All available data views can be found in the category data of the scene graph.

In its initial state, a data view updates itself ten times per second with data received from the robot. However, when a field is selected to be edited, the updates stop to preserve the changes that are made. If the editing is finished by either pressing Enter or by deselecting the field, the following state depends on whether the field's value was actually changed. If not, the data view returns to updating itself with data from the robot. If it was changed, the updates are not continued to keep the changes. The view is then in its modified state. This is indicated by an asteriks at the end of the view's title. You can discard the changes and return to updating the view with robot data by selecting Reset in its context menu.

However, if Auto-set is enabled, which it is by default, the modified state is skipped and the changed data is immediately sent to the robot, continuously overwriting the original data. This corresponds to the console command set. This state is indicated by an upward arrow at the end of the view's title. The context menu item Unchanged stops overwriting the data on the robot and returns to updating the view with data received from the robot. This does not necessarily discard the changes, because the robot code might preserve them. Without Auto-set, the robot data can be overwritten by manually selecting the context menu item Set.

Log Player View¶

The log player allows to control the replay of log files using the following buttons:

Button	Shortcut	Function
	Space	Start playback
	Space	Pause playback
	Home	Stop playback
	End	Replay the current frame
	PageUp	Go 100 frames back
	Up	Go to the previous frame with an image
	Left	Go to the previous frame
	Right	Go to the next frame
	Down	Go to the next frame with an image
	PageDown	Go 100 frames forward
		Run in a loop, i.e. continue at the beginning after the end is reached

The shortcuts only work if the focus is not in the console view. In addition, the current frame can be directly entered as a number or selected using a slider.

Annotation View¶

The annotation view displays all annotations (cf. this section) contained in a log file. Double clicking an annotation will cause the log file to jump to the given frame number.

It is also possible to view annotations in real-time when using the simulated NAO or a direct debug connection to a real NAO. This has to be activated by using the following debug request:

dr annotation

Scene Description Files¶

The language of scene description files is an extended version of RoSiML¹. Scene files that use SimRobotCore2 have to end with .ros2, such as BH.ros2. In the following, the most important elements, which are necessary to add robots, dummies, and balls, are shortly described (based upon BH.ros2). For a more detailed documentation, see the documentation in the SimRobot repository.

• <Include href="...">: First of all the descriptions of the NAO itself, a specific setup of NAOs, the ball and the field are included. The names of include files end with .rsi2.
• <Scene ...>: This element begins the instantiation section of the scene description. While everything outside the scene element, i.e. the files included above, only declares templates for objects, everything that follows is actually instantiated in the scene. The attributes of this element define some important properties of the scene, e.g. the controller library and the duration of each simulation step.
• <Compound ref="teams"/>: This compound contains two sub-compounds that define (via the names of their three sub-compounds) the team number, field player and goalkeeper color of the first and second team for the simulated GameController. This is mainly important to make the jersey detection work in the simulation and does not have an effect on the actual appearance of the robots (see below).
• <Compound ref="robots"/>: This compound a macro that contains all active robots, i.e. robots for which will be controlled by the B-Human modules. However, each of them will require a lot of computation time. In the tag Body, the attribute ref specifies which NAO model should be used and name sets the robot name in the scene graph of the simulation. Legal robot names are "robot1" ... "robot40", where the first 20 robots are assumed to play in the first team (with player numbers 1...20) while the other 20 play in the second team (again with player numbers 1...20). By the default, the NAO does not wear a jersey. To set a jersey color, use <Set name="NaoColor" value="{color}"> within the Body element, where {color} can be any of the standard jersey color names (e.g. red).
• <Compound ref="extras"/>: This compound contains passive robots (or references a macro that does), i.e. robots that just stand around, but are not controlled by a program. Passive robots can be activated by moving their definition to the original compound robots and changing the referenced model from "NaoDummy" to "Nao".
• <Compound name="balls">: This compound contains an instance of the ball.
• <Compound ref="field"/>: This element instantiates the field from the included file as part of the scene.

Optionally, a scene description file can set the location and scenario (cf. this section) that is used in the simulated robot code. This is done (similar to setting the team colors) by adding Compound elements in the Scene element. The location compound must contain exactly one sub-compound with the name of the selected location (it is not possible to set different locations per team). The scenarios compound can contain either one or two sub-compounds. If only one is present, this scenario will be used for both teams. If two elements are present, they will be used for the first and second team, respectively.

Example:

<Compound name="location">
  <Compound name="MyLocation"/><!-- Location for both teams -->
</Compound>
<Compound name="scenarios">
  <Compound name="MyScenario1"/><!-- Scenario for first team -->
  <Compound name="MyScenario2"/><!-- Scenario for second team -->
</Compound>

Predefined Scenes¶

A lot of scene description files can be found in Config/Scenes. There are two types of scene description files: the ones required to simulate one or more robots, and the ones that connect to a real robot.

Simulating multiple robots is expensive. To overcome this and enable decent frame rates, some scenes come in special variants. In scenes ending with PerceptOracle, no camera images are rendered and percepts are provided by the simulator. However, models, for example the BallModel, still have to be calculated. This is different in the scenes with the suffix Fast, in which even the models are replaced with ground truth data from the simulator.

• BH[PerceptOracle|Fast]: A single robot with five dummies.
• OneTeam[PerceptOracle|Fast]: A team of five robots against dummies.
• Game[PerceptOracle|Fast]: A game five against five.
• ReplayRobot: Replays a log file (cf. this section).
• RemoteRobot: Connects to a remote robot and displays images and data.

Console Commands¶

Console commands can either be directly typed into the console window or they can be executed from a script file. There are three different kinds of commands. The first kind will typically be used in a script file that is executed when the simulation is started. The second kind are global commands that change the state of the whole simulation. The third type is robot commands that affect currently selected robots only (see command robot to find out how to select robots).

Initialization Commands¶

• sc <name> <a.b.c.d>: Starts a remote connection to a real robot. The first parameter defines the name that will be used for the robot. The second parameter specifies the IP address of the robot. The command will add a new robot to the list of available robots using name, and it adds a set of views to the scene graph. When the simulation is reset or the simulator is exited, the connection will be terminated.
• sl <name> [<file> [<scenario> [<location>]]]: Replays a log file. The command will instantiate a complete set of threads and views. The threads will be fed with the contents of the log file. The first parameter of the command defines the name of the virtual robot. The name can be used in the robot command (see below), and all views of this particular virtual robot will be identified by this name in the tree view. The second parameter specifies the path to the log file. If the path is not an absolute path, Config/Logs is the base directory. .log is the default extension of log files. It will be automatically added if no extension is given. If no file is given at all, the previously started log file is used. A scenario and a location can be specified, which will supersede these settings stored in the log file. When replaying a log file, the replay can be controlled by the Log Player (cf. this section) or the command log (see below). It is even possible to load a different log file during the replay.

Global Commands¶

• ar {<feature>} ( off | on ): Enables or disables the entire automatic referee or individual features. The features are trueGameState, placeBall, placePlayers, switchToSet, switchToPlaying, switchToFinished, ballOut, freeKickComplete, clearBall, penalizeLeavingTheField, penalizeIllegalPosition, penalizeIllegalPositionInSet, and unpenalize.
• call <file> [<file>]: Executes a script file. A script file contains commands as specified here, one command per line. The default location for scripts is the Config/Scenes directory, their default extension is .con. If the optional script file is present, that one is executed instead.
• ci off | on | <fps>: Switches the calculation of images on or off. If an image frame rate is explicitly specified instead of on, that one is used instead of the default value of 60 Hz. The simulation of the robot's camera image costs a lot of time, especially if several robots are simulated. In some development situations, it is better to switch off all low level processing of the robots and to work with ground truth world states, i.e., world states that are directly delivered by the simulator. In such cases there is no need to waste processing power by calculating camera images. Therefore, it can be switched off. However, by default this option is switched on. Note that this command only has an effect on simulated robots.
• cls: Clears the console window.
• dt off | on | <fps>: Switches simulation dragging to real-time on or off. If a frame rate is explicitly specified instead of "on", that one is used instead of the default value of 83.3 Hz. Normally, the simulation tries not to run faster than real-time. Thereby, it also reduces the general computational load of the computer. However, in some situations it is desirable to execute the simulation as fast as possible. By default, this option is activated.
• echo <text>: Prints text into the console window. The command is useful in script files to print commands that can later be activated manually by pressing the Enter key in the printed line.
• gc initial | ready | set | playing | finished | goalByFirstTeam | goalBySecondTeam | kickOffFirstTeam | kickOffSecondTeam | goalKickForFirstTeam | goalKickForSecondTeam | pushingFreeKickForFirstTeam | pushingFreeKickForSecondTeam | cornerKickForFirstTeam | cornerKickForSecondTeam | kickInForFirstTeam | kickInForSecondTeam | penaltyKickForFirstTeam | penaltyKickForSecondTeam | halfFirst | halfSecond | gameNormal | gamePenaltyShootout | competitionPhasePlayoff | competitionPhaseRoundRobin | competitionTypeChampionsCup | competitionTypeChallengeShield: Sets the current state of the GameController.
• ( help | ? ) [<pattern>]: Displays a help text. If a pattern is specified, only those lines of the help are printed that contain the pattern.
• mvo <name> <x> <y> <z> [<rotx> <roty> <rotz>]: Moves the object with the given name to the given position and optionally rotates it.
• robot ? | all | <name> {<name>}: Selects a robot or a group of robots. The console commands described in the next section are only sent to selected robots. By default, only the robot that was created or connected last is selected. Using the robot command, this selection can be changed. Type robot ? to display a list of the names of available robots. A single simulated robot can also be selected by double-clicking it in the scene view. To select all robots, type robot all.
• st off | on: Switches the simulation of time on or off. Without the simulation of time, all calls to Time::getCurrentSystemTime() will return the real time of the PC. However if the simulator runs slower than real-time, the simulated robots will receive less sensor readings than the real ones. If the simulation of time is switched on, each step of the simulator will advance the time by 12 ms. Thus, the simulator simulates real-time, but it is running slower. By default this option is switched off.
• # <text>: Begins a comment line. Useful in script files.

Robot Commands¶

• bc [<red%> [<green%> [<blue%>]]]: Defines the background color for 3-D views. The color is specified in percentages of red, green, and blue intensities. All parameters are optional. Missing parameters will be interpreted as 0%.
• dr ? [<pattern>] | off | <key> ( off | on ): Sends a debug request. B-Human uses debug requests to switch debug responses (cf. this section) on or off at runtime. Type dr ? to get a list of all available debug requests. The resulting list can be shortened by specifying a search pattern after the question mark. Debug responses can be activated or deactivated. They are deactivated by default. Specifying just off as the only parameter returns to this default state. Several other commands also implicitly send debug requests, e.g. to activate the transmission of debug drawings.
• for <thread> {<thread>} ( dr | get | mr | set | si | vf | vi | vp ) {<param>}: Reduces the effect of certain commands to a set of threads. See the documentation of the individual commands for a description of their parameters.
• get ? [<pattern>] | <key> [ ? | save [<file>]]: Shows or saves debug data or shows its specification. This command allows displaying any information that is provided in the robot code via the MODIFY macro. If one of the strings that are used as first parameter of the MODIFY macro is used as parameter of this command (the modify key), the related data will be requested from the robot code and displayed. The output of the command is one or more valid set commands (see below) that can be changed to modify data on the robot. A question mark directly after the command (with an optional filter pattern) will list all the modify keys that are available. A question mark after a modify key will display the structure of the associated data type rather than the data itself. With the option save, the data will be saved to a file instead of shown. If no file is specified, its name is automatically generated from the modify key and its first occurrence in the search path is overwritten if it exists. If not, the file is directly created in the folder Config.
• jc hide | show | motion ( 1 | 2 ) <command> | ( press | release ) <button> <command>: Sets a joystick command. If the first parameter is press or release, the number following is interpreted as the number of a joystick button. Legal numbers are between 1 and 40. Any text after this first parameter is part of the second parameter. The <command> parameter can contain any legal script command that will be executed in every frame while the corresponding button is pressed. The prefixes press or release restrict the execution to the corresponding event. The commands associated with the 26 first buttons can also be executed by pressing Ctrl+Shift+A... Ctrl+Shift+Z on the keyboard. If the first parameter is motion, an analog joystick command is defined. There are two slots for such commands, number 1 and 2, e.g., to independently control the robot's walking direction and its head. The remaining text defines a command that is executed whenever the readings of the analog joystick change. Within this command, $1...$8 can be used as placeholders for up to eight joystick axes. The scaling of the values of these axes is defined by the command js (see below). If the first parameter is show, any command executed will also be printed in the console window. hide will switch this feature off again, and hide is also the default.
• jm <axis> <button> <button>: Maps two buttons on an axis. Pressing the first button emulates pushing the axis to its positive maximum speed. Pressing the second button results in the negative maximum speed. The command is useful when more axes are required to control a robot than the joystick used actually has.
• js <axis> <speed> <threshold> [<center>]: Sets the axis maximum speed and ignore threshold for command jc motion. axis is the number of the joystick axis to configure (1...8). speed defines the maximum value for that axis, i.e., the resulting range of values will be [-speed...speed]. The threshold defines a joystick measuring range around zero in which the joystick will still be recognized as centered, i.e., the output value will be 0. The threshold can be set between 0 and 1. An optional parameter allows for shifting the center itself, e.g. to compensate for bad calibration of a joystick.
• log ...: This command supports both recording and replaying log files. The latter is only possible if the current set of robot instances was created using the initialization command sl (cf. this section). This command has several sub-commands, i.e. the following commands are parameters of the log command, such as log start.
  • ? [<pattern>]: Prints statistics on the messages contained in the current log file. The optional pattern limits output to messages corresponding to the pattern.
  • mr [list]: Sets the provider of all representations from the log file to LogDataProvider. If list is specified the module request commands will be printed to the console instead.
  • start | stop: If replaying a log file, starts and stops the replay. Otherwise, the commands will start and stop the recording.
  • pause | forward [ fast | image ] | backward [ fast | image ] | repeat | goto <number> | time <minutes> <seconds>: Controls replay of a log file. pause stops the replay without rewinding to the beginning, forward and backward advance a single step in the respective direction. The option fast increases the step size to 100. In contrast, the option image steps to a frame containing an image, skipping all frames in between that do not. repeat just resends the messages from the current frame. goto allows jumping to a certain frame in the log file. If the log file contains the representation GameInfo, the command time allows to jump to the first frame with a certain remaining game time.
  • cycle | once: Decides whether the log file is replayed only once or continuously repeated.
  • clear | ( keep | remove ) <message> {<message>}: clear removes all messages from the log file, while keep and remove only delete a selected subset based on the set of message IDs specified.
  • ( load | save ) <file>: These commands load or save the log file stored in memory from or to a file, respectively. If the filename is not a absolute path, it is relative to Config/Logs. Otherwise, the full path is used. .log is the default extension of log files. It will be automatically added if no extension is given.
  • trim ( until <end frame> | from <start frame> | between <start frame> <end frame> ): Keeps only the given section of the log. In addition to integer numbers, current can also be used to refer to the current frame.
  • saveAudio [<file>]: Saves the audio data from the current log file to a .wav file. If no filename is given, the file is created at the log file's location with the .wav extension. If the specified filename is not an absolute path, it is relative to Config/Sounds.
  • saveImages [raw] [onlyPlaying] [<takeEachNth>] [<dir>]: Saves images from the current log file as PNG files to a directory. If raw is specified, images are left in their YUV format, otherwise they are converted to RGB. onlyPlaying only selects images that were taken while the robot was in the playing state, unpenalized and upright. Images can be skipped using the parameter takeEachNth. If no target directory is given, the images are put in a new directory next to the log file. If the specified directory is not an absolute path, it is relative to Config/Images.
• msg off | on | log <file> | disable | enable: Switches the output of text messages on or off, or redirects them to a text file. All threads can send text messages via their message queues to the console window. As this can disturb entering text into the console window, printing can be switched off. However, by default text messages are printed. In addition, text messages can be stored in a log file, even if their output is switched off. The file name has to be specified after msg log. If the file already exists, it will be replaced. If no path is given, Config/Logs is used as default. Otherwise, the full path is used. .txt is the default extension of text log files. It will be automatically added if no extension is given. enable and disable can switch between handling messages from the robot at all, which is enabled by default.
• mr ? [<pattern>] | modules [<pattern>] | save | <representation> ( ? [<pattern>] | <module> | off | default ): Sends a module request. This command allows selecting the module that provides a certain representation in a certain thread. If the representation is currently provided in exactly one thread, the command can be used directly. Otherwise, it must be prefixed by for to define for which thread(s) the command should apply. If a representation should not be provided anymore, it can be switched off. Deactivating the provision of a representation is usually only possible if no other module requires that representation. Otherwise, an error message is printed and the robot is still using its previous module configuration. Sometimes, it is desirable to be able to deactivate the provision of a representation without the requirement to deactivate the provision of all other representations that depend on it. In that case, the provider of the representation can be set to default. Thus no module updates the representation and it simply keeps its previous state. A question mark after the command lists all representations. A question mark after a representation lists all modules that provide this representation. The parameter modules lists all modules with their requirements and provisions. All three listings can be filtered by an optional pattern. save saves the current module configuration to the file threads.cfg which it was originally loaded from. Note that this usually has not the desired effect, because the module configuration has already been changed by the start script to be compatible with the simulator. Therefore, it will not work anymore on a real robot. The only configuration in which the command makes sense is when communicating with a remote robot.
• mv <x> <y> <z> [<rotx> <roty> <rotz>]: Moves the selected simulated robot to the given position and rotates it if a rotation is specified. x, y, and z have to be specified in mm, the rotations have to be specified in degrees. Note that the origin of the NAO is about 330 mm above the ground, so z should be 330.
• mvb <x> <y> <z>: Moves the ball to the given position. x, y, and z have to be specified in mm. Note that the radius of the ball is 50 mm above the ground, so z should be at least 50.
• poll: Polls for all available debug requests and debug drawings. Debug requests and debug drawings are dynamically defined in the robot control program. Before console commands that use them can be executed, the simulator must first determine which identifiers exist in the code that currently runs. Although the acquisition of this information is usually done automatically, e.g. after the module configuration was changed, there are some situations in which a manual execution of the command poll is required. For instance if debug responses or debug drawings are defined inside another debug response, executing poll is necessary to recognize the new identifiers after the outer debug response has been activated.
• pr none | illegalBallContact | playerPushing | illegalMotionInSet | inactivePlayer | illegalPosition | leavingTheField | requestForPickup | localGameStuck | illegalPositionInSet | playerStance | substitute | manual: Penalizes a simulated robot with the given penalty or unpenalizes it when used with none. If the automatic referee is turned on, the necessary placement is done automatically: When penalized, the simulated robot will be moved to the sideline, looking away from the field. When unpenalized, it will be turned, facing the field again, and moved to the sideline that is further away from the ball.
• set ? [<pattern>] | <key> ( ? | unchanged | <data>): Changes debug data or shows its specification. This command allows changing any information that is provided in the robot code via the MODIFY macro. If one of the strings that are used as first parameter of the MODIFY macro is used as parameter of this command (the modify key), the related data in the robot code will be replaced by the data structure specified as second parameter. It is best to first create a valid set command using the get command (see above). Afterwards that command can be changed before it is executed. If the second parameter is the key word unchanged, the related MODIFY statement in the code does not overwrite the data anymore, i.e. it is deactivated again. A question mark directly after the command (with an optional filter pattern) will list all the modify keys that are available. A question mark after a modify key will display the structure of the associated data type rather than the data itself.
• si reset [<number>] | [number] [grayscale] [<file>]: Saves the raw image of a robot. The image will be saved in the format derived from the file extension in color, unless the grayscale option is specified. If no path is specified, Config/raw_image.bmp will be used as default. If number is specified, a number is appended to the filename that is increased each time the command is executed. The option reset resets the counter to a specified value or 0 if none is specified. It is the only option that can be used without specifying the thread that provides the image using the prefix for.
• sn [ whiteNoise | timeDelay | discretization ] [ on | off ]: (De)activates the simulation of (specified) sensor noise. Currently, implemented noise types are whiteNoise of the IMU, discretization of the joint angle sensors and the fact that new data from the gyroscope or accelerometer comes alternating only every second frame. If no type of noise is specified the change is applied to all.
• vf <name>: Adds a field view (cf. this section). A field view is the means for displaying debug drawings in field coordinates. The parameter defines the name of the view. If a thread is specified using the prefix command for, debug drawings from that thread will be preferred, i.e. drawings that could be provided by that thread will be ignored from others.
• vfd ? [<pattern>] | off | ( all | <name> ) ( ? [<pattern>] | <drawing> [ on | off ] ): (De)activates a debug drawing in a field view. The first parameter is the name of a field view that has been created using the command vf (see above) or all to add the drawing to all field views. The second parameter is the name of a drawing that is defined in the robot control program. Such a drawing is activated if the third parameter is on or is missing. It is deactivated if the third parameter is off. The drawings will be drawn in the sequence they are added, from back to front. Adding a drawing a second time will move it to the front unless the drawing is an origin drawing (those can be "drawn" multiple times). A question mark directly after the command will list all available field views. A question after a valid field view will list all available field drawings. Both question marks have an optional filter pattern that reduces the number of answers. vfd off will turn off all debug drawings except for the background in all field views.
• vi ? [<pattern>] | ( <image> | none ) [<name>] [ gain <value>] [ddScale <value>]: Adds an image view (cf. this section). An image view is the means for displaying debug drawings in image coordinates. If an image is specified, the prefix for must be used to define the thread that should provide the image in case more than one thread can do so. The image can either be the camera image (CameraImage or JPEGImage), a debug image (defined by the SEND_DEBUG_IMAGE macro, e.g. GrayscaledImage), or no image at all (none). If a thread is specified using the prefix command for or implicitly by specifying an image, debug drawings from that thread will be preferred, i.e. drawings that could be provided by that thread will be ignored from others. The next parameter is the name of the view that is needed when adding drawings to it. If the name is not given, it will be the same as the name of the image and the name of the thread from which the image is taken. With the argument of the gain parameter the image gain can be adjusted, if no gain is specified the default value will be 1.0. The argument of ddScale can set a custom scaling of debug drawings in the view, which is 1.0 by default. A question mark followed by an optional filter pattern will list all available images.
• vic ? [<pattern>] | ( all | <name> ) [ alt | noalt ] [ ctrl | noctrl ] [ shift | noshift ] <command>: Sets a command to be executed when clicking on an image view. The first parameter is the name of an image view that has been created using the command vi (see above) or all to set the command for all image views. Then, for the modifier keys Alt, Control and Shift, it can be selected whether they either must or must not be pressed while clicking for the command to be executed. Modifiers that are not mentioned at all are ignored. Everything after the modifier specification is the command that will be executed on clicking the image view. In the command, the placeholders $1...$3 can be used to insert the x-coordinate, y-coordinate and the lower case thread identifier to which the image view belongs, respectively. A question mark directly after the command will list all available image views.
• vid ? [<pattern>] | off | ( all | <name> ) ( ? [<pattern>] | <drawing> [ on | off ] ): (De)activates a debug drawing in an image view. The first parameter is the name of an image view that has been created using the command vi (see above) or all to add the drawing to all image views. The second parameter is the name of a drawing that is defined in the robot control program. Such a drawing is activated if the third parameter is on or is missing. It is deactivated if the third parameter is off. The drawings will be drawn in the sequence they are added, from back to front. Adding a drawing a second time will move it to the front. A question mark directly after the command will list all available image views. A question mark after a valid image view will list all available image drawings. Both question marks have an optional filter pattern that reduces the number of answers. vid off will turn off all debug drawings in all image views.
• vp <name> <numOfValues> <minValue> <maxValue> [<yUnit> [<xUnit> [<xScale>]]]: Adds a plot view (cf. this section). A plot view is the means for plotting data that was defined by the macro PLOT in the robot control program. The first parameter defines the name of the view. The second parameter is the number of entries in the plot, i.e. the size of the x axis. The plot view stores the last numOfValues data points sent for each plot and displays them. minValue and maxValue define the range of the y axis. The optional parameters can improve the appearance of the plots by adding labels to both axes and by scaling the time-axis. The axis label drawing can be toggled by using the context menu of the plot view. If a thread is specified using the prefix command for, plots from that thread will be preferred, i.e. plots that could be provided by that thread will be ignored from others.
• vpd ? [<pattern>] | <name> ( ? [<pattern>] | <drawing> ( ? [<pattern>] | <color> [<description>] | off ) ): Plots data in a certain color in a plot view. The first parameter is the name of a plot view that has been created using the command vp (see above). The second parameter is the name of plot data that is defined in the robot control program. The third parameter defines the color for the plot. white, black, red, green, blue, yellow, cyan, magenta, orange, violet, gray, brown, and six-digit hexadecimal RGB color codes are supported. An optional fourth parameter can set a custom description of the plot data. The plot is deactivated when the third parameter is off. The plots will be drawn in the sequence they were added, from back to front. Adding a plot a second time will move it to the front. A question mark directly after the command will list all available plot views. A question after a valid plot view will list all available plot data. A question mark after a valid plot view and a valid plot data identifier will list the available colors. All question marks have an optional filter pattern that reduces the number of answers.

Input Dialogs¶

Input dialogs may be used as placeholders in scripting-files to request input from the user. The dialogs will be opened before their respective script-lines are executed and the user selected value handled as usual script, e.g. a command or parameter. In the following list, the outer curly braces are literals.

• ${<label>}: This expression opens a plain text input dialog.
• ${<label>,<relativePath>}: This expression opens a file selection dialog at the relative path. The path may also specify legal file names via the asterisk-character (*). This is used, e.g., in the file Config/Scenes/Include/replayDialog.con: ${Log File:,../../Logs/*.log}.
• ${<label>,,<relativePath>}: This expression opens a directory selection dialog at the relative path.
• ${<label>,<value-1>,<value-2>{,<value-n>}}: This expression opens a drop-down list with the respective name and value options. This is used, e.g., to open an IP address dialog in the file Config/Scenes/Include/connectDialog.con: ${IP address:,10.0.1.1,192.168.1.1}.