Getting Started¶

This chapter describes how to use or code on Windows, macOS, and Linux. The code can be built for our simulator and for the actual robot (NAO V6 only). We first show how to compile the code before we describe how to setup a NAO robot to be used with our software. If you want to setup a NAO and run our code, you will need access to a NAO operating system image in version 2.8.5.11 (called nao-2.8.5.11_ROBOCUP_ONLY_with_root.opn), which is not publicly available. The RoboCup Standard Platform League Technical Committee can give you access if you already joined the league or plan to do so. Without that special version of the operating system, generating our own image will not work.

This manual assumes that you cloned the B-Human repository including the submodules. All paths mentioned in this description will be relative to the main directory of the working copy. The version numbers of software that we specify are the ones we currently use. That does not mean that newer or older versions will not work, but it is not guaranteed that they will.

Targets and Configurations¶

The B-Human project consists of the main build targets SimRobot, Nao, bush, and Tests (cf. this table). These targets can all be built in three different configurations¹ (cf. this table). The general idea is that Debug contains all debugging support, but is slow, Release sacrifices debugging support for speed, and Develop is a reasonable compromise between the two. The actual selection of features depends on the platform.

Target	Description
SimRobot	The code is built to run in simulation. The whole build consists of our simulator SimRobot together with its libraries SimRobotCommon, SimRobotCore2, SimRobotCore2D, and SimRobotEditor and the robot control program SimulatedNao. The connection between the robot control program and the simulator is implemented in the library Controller, which also relies on building the library qtpropertybrowser.
Nao	The code is built to run on the NAO.
bush	The B-Human User Shell is a tool to deploy and manage multiple robots at the same time.
Tests	Some unit tests. On macOS, this target is available by selecting SimRobot and then switching to Xcode's Tests Navigator.

Build targets of the B-Human system.

	without assertions (`NDEBUG`)	debug symbols (compiler flags)	debug libs² (`_DEBUG`, compiler flags)	optimizations (compiler flags)	debugging support³
Release
Nao	✓	✗	✗	✓	✗
SimulatedNao	✓	✗	✗	✓	✓
SimRobot	✓	✗	✗	✓
Develop
Nao	✗	✗	✗	✓	✓
SimulatedNao	✗	✓	✗	✗	✓
SimRobot	✓	✗	✗	✓
Debug
Nao	✗	✓	✓	✗	✓
SimulatedNao	✗	✓	✓	✗	✓
SimRobot	✗	✓	✓	✗

Effects of the different build configurations. SimRobot represents everything in the simulation except for SimulatedNao.

Building the Code¶

Microsoft Windows¶

Prerequisites¶

Microsoft Windows 10 64 bit Version 21H1
Microsoft Visual Studio Community 2019 Version 16.11.2. Installing the workload Desktop development with C++ (including the packages MSVC v142 - VS 2019 C++ x64/x86 build tools, Windows 10 SDK 10.0.19041.0, and C++-ATL for latest v142 build tools (x86 & x64)) is sufficient.
CMake 3.21.2
- Use a Windows x64 installer from here. Visual Studio's integrated CMake support does not work.
- Select the option "Add CMake to the system PATH for all users".
Windows Subsystem for Linux (WSL). Execute the PowerShell script Make/VS2019/installWSL.ps1. You have to confirm that executing the script is allowed. The script will install the Windows Subsystem for Linux (unless it is already installed) and ask for a reboot of the computer. Afterwards, the script has to be executed again to download and install Ubuntu 20.04 into Util/WSL with all packages required.

Compiling¶

Run Make/VS2019/generate.cmd as administrator (on the first run, the script creates a symlink) and open the solution Make/VS2019/B-Human.sln in Visual Studio. Select the desired configuration (Develop is a good start) and build one of the targets mentioned in this section⁴. Either SimRobot or Utils/bush can be selected as StartUp Project to run it.

macOS¶

Prerequisites¶

macOS 11.5.2 (Intel or ARM)
Xcode 12.5.1
CMake 3.21.1
- Use a "macOS 10.13 or later" .dmg from here. CMake installations via Homebrew do not work.

Compiling¶

Xcode must have been executed at least once before to accept its license and to install its components. Run Make/macOS/generate and open the Xcode project Make/macOS/B-Human.xcodeproj. The schemes in the toolbar allow building the targets mentioned in this section in different configurations.

On ARM machines, there is also the option to run Make/macOS/generate -r to generate an Xcode project that will still compile Intel code, which runs via Rosetta 2. A reason for doing so is that our library CompiledNN to efficiently compute neural networks does not work on ARM machines yet. As a replacement, the ONNX runtime is used. It is significantly slower than CompiledNN and requires the neural networks to be present in a second format (i.e. .onnx). Therefore, in some situations it might be more convenient to still use Intel code on ARM machines.

When building for the NAO (always Intel code), running the target will open a dialog to deploy the code to a robot. This will only work if the robot was already set up to work with our software (cf. this section), unless creating an installation image is selected as target (cf. this section). If the script Make/macOS/login was used before to login to a NAO, the IP address used will be provided as default. Both the IP address selected and the options specified are remembered for the next use of the deploy dialog. The IP address is stored in the file Config/Scenes/Includes/connect.con that is also written by the script Make/macOS/login and used by the simulator scene Config/Scenes/RemoteRobot.ros2. The options are stored in Make/Common/deploy-options.txt.

Support for Xcode¶

Calling the script Make/macOS/generate also installs various development supports for Xcode:

Data formatters. If the respective file does not already exist, a symbolic link is created to formatters that let Xcode’s debugger display summaries of several Eigen datatypes.
Source file templates. Xcode’s context menu entry New File... contains a category B-Human that allows to create some B-Human-specific source files.
Code snippets. Many code snippets are available that allow adding standard constructs following B-Human’s coding style as well as some of B-Human’s macros.
Source code formatter. A system text service for formatting the currently selected text is available in the menu Xcode→Services→AStyle for B-Human.

Recommended Settings for Xcode¶

B-Human uses UTF-8, no tabulator characters, and an indentation width of 2:

Xcode|Preferences|Text Editing|Editing|Default text encoding|Unicode (UTF-8)
Xcode|Preferences|Text Editing|Indentation|Prefer indent using|Spaces
Xcode|Preferences|Text Editing|Indentation|Indent width|2

Linux¶

Prerequisites¶

A 64-bit Linux, e.g. Ubuntu 20.04.3 LTS

The following packages (here for Ubuntu 20.04.3 LTS):

sudo apt install clang cmake git graphviz libasound-dev libglew-dev libqt5opengl5-dev libqt5svg5-dev lld llvm net-tools ninja-build pigz qtbase5-dev rsync wish xterm xxd

(optionally) CLion 2019.3 or newer

Project Generation¶

Run Make/Linux/generate to generate CLion project files or run the same script with the shell variable NO_CLION set to true (e.g. NO_CLION=true Make/Linux/generate) to generate CMake caches directly. You will be prompted for your password in order to change permissions on a binary that checks the status of modifier keys which is needed for the deploy window.

Compiling (no IDE)¶

Run Make/Linux/compile [<target>] [<configuration>] to compile the code (using a target and configuration from this section, Develop is the default configuration).

Compiling (CLion)¶

Open Make/Linux/CMakeLists.txt in CLion as project (not the one in Make/Common). Targets and configurations are preconfigured and can be selected in the run manager.

Setting Up the NAO¶

In the Standard Platform League, each team is assigned a unique team number. This number is used to identify the team in the GameController application, but it is also used to avoid conflicts in IP addresses and UDP ports. In the B-Human system, the team number must be entered into the file Config/settings.cfg as well as the team port (team number plus 10000). When deploying with the bush, the team number can also be specified there, but scripts usually look it up in the file Config/settings.cfg.

IP Configuration¶

All NAOs will be set up to use specific subnet addresses for wired and wireless communication. The default values are configured in Install/createRobot and are 192.168.<team>.<robot> for wired and 10.0.<team>.<robot> for wireless communication (usually the setup used at RoboCup events). You have to edit this files if you want to use different subnets before you create configurations for individual robots.

The IP addresses that unknown robots (i.e. robots that are not created ahead of time using createRobot, e.g. at a remote event) get are set in Install/createHomeArchive. The code release does not support multiple unknown robots to be deployed with different IP addresses.

Wireless Network Configuration¶

Wireless configurations are stored in Install/Profiles as snippets of a netplan configuration file within the access-points mapping (see here. The profile that is active after the first boot can be set using the -w option of the deploy script when creating the image. The special empty profile NONE will turn off wireless. Other profiles can be selected later, when deploying the software to the robot. The profiles will not only be copied to the NAO during its initial setup, but also be updated while deploying our software, i.e. the contents of the directory can be changed later.

Creating a Robot Configuration¶

Only once for each NAO and while being connected to that NAO, run

Install/createRobot [-t <team>] -r <robot> -i <ip> <name>

<team> is your team’s number (the third number of the robot’s target IP address). If omitted, the team number from the file Config/settings.cfg is used. <robot> is the number of the robot (the fourth number of its target IP address). <ip> is its current IP address. <name> is the name you will use to refer to the NAO in the future (it must be a valid host and directory name). The script will create files in Install/Robots/<name> and Config/Robots/<name> and update some existing configuration files.

If a network connection to the NAO is not possible, the alternative form

Install/createRobot [-t <team>] -r <robot> -s <head> -b <body> <name>

can be used, where <head> and <body> body are the serial numbers of the head and body, respectively (20-character-strings starting with P).

Creating a Root Image¶

In order to run the B-Human software on a robot, it must be flashed with a B-Human-specific operating system image. This image contains two parts: An .ext3 image of the root file system that contains the basic operating system and a tar.gz archive that is extracted on the /home partition. While the latter is automatically created as part of the deploy script with the -i option (cf. this section), the former must be done manually. It only needs to be done once (or whenever some of the included files change or you want to install different packages) and you can redistribute the resulting image among your team members. The process only works on Ubuntu and requires the original SoftBank operating system image (nao-2.8.5.11_ROBOCUP_ONLY_with_root.opn) and the following additional packages:

sudo apt install debootstrap patchelf

The following command creates the root image, which will download a lot of packages and can take a few minutes:

sudo Install/createRootImage <path to original SoftBank OPN>

This results in the file Install/root.ext3.

Flashing the Robot¶

Using the root image created above, each robot must be flashed with an operating system image before it can be used. See the description of the -i option in the next section.

Deploying the Software¶

Deploying the software to a NAO means copying the directory Config (without the subdirectories Images, Keys, Logs, and Scenes) together with the executable bhuman to /home/nao/Config on the robot. In addition, the network profiles in Install/Profiles are copied to /home/nao/Profiles. The latter does not automatically update the current network profile.

The software is deployed by executing the script Make/Common/deploy that is also linked from some other subdirectories under Make:

usage: deploy [Release|Develop|Debug] [<ipaddress>|(-r <playernumber> <ipaddress>)*] {options}
  options:
    -b                     restart bhuman
    -c <team color>        set team color to blue, red, yellow, black, white, orange, purple, brown, or gray
    -d                     delete logs or add timestamp to image
    -h | --help | /h | /?  print this text
    -i                     create image instead of deploying
    -l <location>          set location
    -m <magic number>      set magic number for teamcomm (0-255). Set -1 for random.
    -nc                    never compile
    -nr                    do not check whether target is reachable
    -o <team port>         overwrite team port
    -p <player number>     set player number
    -r <n> <ip>            copy to <ip> and set playernumber to <n> (one -r per robot)
    -s <scenario>          set scenario
    -t <team number>       set team number
    -u                     check for a USB drive before starting bhuman (only when creating an image)
    -v <volume percent>    set NAO's volume
    -w <wireless profile>  set wireless profile
  examples:
    ./deploy Develop 192.168.5.14 -p 1
    ./deploy Release -r 1 10.0.5.14 -r 3 10.0.0.2
    ./deploy Release -i -nc -v 50 -w SPL_A

Without the option -nc, deploy will build the code before deploying it. The script is also called by Visual Studio when building the project Utils/deploy, by CLion when starting the target Nao, and by Xcode when building the scheme Nao. In those cases, the configuration (Debug/Develop/Release) is automatically provided to the script. In CLion and Xcode, there is an additional option -a, which prevents the deploy dialog from being shown in the future. Instead, the current parameters will be reused, i.e. building the code will automatically deploy it without any questions asked. To get the dialog back, hold down the key Ctrl (Shift with CLion) at the time the dialog would normally appear.

With the option -i, an installation image (.opn) is created instead of copying the software to an actual robot. In that case, no IP address has to be specified. The image will be stored in the directory Build/Image/<configuration>/ and can be used to install the robot following these instructions. Before flashing the image, the NAO must have run the original SoftBank image nao-2.8.5.11_ROBOCUP_ONLY_with_root.opn, as otherwise the firmware of the embedded boards may not be compatible.

The standard method for deploying our software to multiple NAOs is the B-Human User Shell (bush, see this chapter). It is a graphical frontend for deploy with a lot of additional functionality.

Working with the NAO¶

After pressing the chest button to turn on the NAO, it takes about 25 seconds until our software runs. It is important not to move the NAO while it is booting up, because it calibrates its gyroscopes during this time. Our software will give an acoustic alarm if the gyroscope was not calibrated correctly. In that case, the robot has to be rebooted.

To connect to the NAO, the subdirectories of Make contain a login script for each supported platform. The only parameter of that script is the IP address of the robot to login. It automatically uses the appropriate SSH key to login. In addition, the IP address specified is written to the file Config/Scenes/Includes/connect.con. Thus a later use of the SimRobot scene RemoteRobot.ros2 will automatically connect to the same robot. On macOS and in CLion, the IP address is also the default address for deployment from the IDE.

There are several scripts to start and stop bhuman via SSH. Those scripts are copied to the NAO upon installing the B-Human software.

bhuman executes the bhuman executable in the foreground. It handles selection of the logging device and redirecting output to a logfile. Press Ctrl+C to terminate the process. Please note that the process will automatically be terminated if the SSH connection is closed. bhuman -d starts a gdb session for the bhuman executable. bhuman -b option disables output to the console and is used by the bhuman systemd service.
setprofile changes the wireless profile.
setvolume changes the sound volume.

Other relevant commands are:

systemctl --user start|stop|restart bhuman.service starts, stops, or restarts the bhuman executable as a background service. The script Make/Common/deploy always stops bhuman before deploying. If deploy is started with the option -b, it will restart bhuman after all files were copied.
sudo systemctl poweroff shuts down the NAO. If bhuman is running, this can also be done by pressing the chest button longer than three seconds (until the robot's eyes turn blue or it starts to sit down).
sudo systemctl reboot reboots the NAO.

Calibrating the NAO¶

The B-Human software expects all parts of the NAO robot to be at specific positions, so it is very important that the robots are calibrated correctly. Uncalibrated robots will probably not be able to walk reliably and in a stable manner. Also, projections from image coordinates to world coordinates (and vice versa) will be wrong, resulting in a multitude of problems. Currently, two components of the robot, the joints and the cameras, require calibration. We recommend checking these calibrations from time to time, especially after the robot was repaired or otherwise abused. Even though we provide a way to automatically calibrate the joints, we only perform such a calibration if we assume the robot in question was calibrated incorrectly, e.g. after a repair. At the moment, none of our NAO V6 robots are in such a state, so we only calibrate the cameras and some sensors.

Joint Calibration¶

Connect to the robot with SimRobot and enter the following command to start the calibration of the joints:

call Calibrators/JointAuto

In the SimRobot console, you will then be asked to tilt the robot and hold it in specific rotations in the air. In general, the robot shall either be held upright or in horizontal position with the robots back facing the floor. While in the air, the robot will move some of its joints to calibrate them automatically. When the robot has finished calibrating its joints, it will report completion in the SimRobot console. You may then use the command

save representation:JointCalibration

to save the joint calibration data in the robot's Config/ directory.

Autonomous Calibration¶

Currently, there are two different modules in the B-Human codebase that perform the autonomous camera calibration. Both modules are largely similar.

By default, the module we used during RoboCup 2021 is active. We noticed some shortcomings, e.g. calibrations that are "good enough" for the robot to participate in a soccer game, but do result in image-to-field projection errors up to half a meter at a distance of only five meters. We therefore also provide a second and somewhat experimental calibration module which may provide better calibration results, but is still a work in progress.

Note

You can use the alternative calibration module by simply setting the scenario option -s ExpCalibration when deploying the robot.

calibrationPose To perform the calibration, place the robot at the sideline of a soccer field, as if the robot would return from a penalty (in line with the penalty cross), facing the penalty cross.

Now you need to bring the robot into the calibration mode, to start the autonomous calibration process. Press the robot's chest button once to bring the robot from the inactive state into the initial state (in which the robot stands upright). Press and hold the front head button and the chest button. After one second the robot switches to the calibration mode, indicated by a blue-purple glowing chest button. Release both buttons.

Note

As long as the chest button shows no color, you can repeat the process. If the robot's chest button glows red (indicating the penalized state), you can press and hold all three head buttons for one second, to bring it back into the inactive state. If the chest button glows green, press the button once to transition into the penalized state, from which you can switch the robot back into the inactive state.

The robot will now walk roughly to the position shown in the image.

calibrationPose

Along the way it will calibrate some of its sensors. The robot will attempt to detect some field lines of the goal area and turn twice. If the robot is unable to detect a field line, it will automatically move the head around or even reposition itself.

Note

When using the alternative calibration module, the robot will not reposition itself, but instead move its head more often. If a field line is not detected, the robot will simply continue. If only a small amount of field lines were detected during the whole calibration procedure, the resulting camera calibration might be very inaccurate. In such a case, deploy or restart the robot and repeat the calibration procedure.

The robot will then stand still and optimize the calibration parameters. The resulting camera calibration will automatically be saved on the robot.

Foot Sole Rotation Calibration¶

Immediately after the camera calibration the robot will turn around and walk around for a bit. It will stop every few steps and stand still for a few seconds. The robot does this to generate calibration values for the foot sole rotations. The resulting representation FootSoleRotationCalibration will be saved on the robot automatically. If this calibration succeeds, some additional features for walking and sensor filtering are active on the robot for an improved performance.

Working with SimRobot¶

On Windows and macOS, SimRobot can either be started from the development environment or by starting a scene description file in Config/Scenes⁵. In the first case, a scene description file has to be opened manually, whereas it will already be loaded in the latter case. On Linux, just run Build/SimRobot/Linux/<configuration>/SimRobot, either from the shell or from a file browser, and load a scene description file afterwards. When a simulation is opened for the first time, only the scene graph is displayed. The simulation is already running, which can be noted from the increasing number of simulation steps shown in the status bar. A scene view showing the soccer field can be opened by double-clicking RoboCup. The view can be adjusted by using the context menu of the window or the toolbar. Double-clicking Console will open a window that shows the output of the robot code and that allows entering commands (cf. this section). All windows can be docked in the main window.

After starting a simulation, a script file is automatically executed if it exists, setting up the robot(s) as desired. The name of the script file is the same as the name of the scene description file but with the extension .con. Together with the ability of SimRobot to store the window layout, the software can be configured to always start with a setup suitable for a certain task.

Although any object in the scene graph can be opened, only displaying certain entries in the object tree makes sense, namely the main scene RoboCup, the objects in the group RoboCup/robots, and all other views, which can be found under the tree roots that are marked with the B-Human logo.

To connect to a real NAO, open the scene Config/Scenes/RemoteRobot.ros2. A prompt will appear to enter the NAO’s IP address.⁶ In a remote connection, the simulation scene contains a robot which mirrors the joint positions of the connected real robot, but otherwise experiences the dynamics of the simulation. All the other views work as usual.

Directory Structure¶

Main Directories¶

Directory	Contents
`Build`	All files created during builds are located in this directory. The directory structure follows the pattern `Build/<os>/<target>/<configuration>`. Deleting the directory will remove all build files. The directory initially does not exist.
`Config`	All configuration files are located in this directory. Some of the subdirectories are described in this section. `Config/Scenes` contains the simulation scenes (`.ros2`) together with the console scripts that are executed when the simulation is started (`.con`)
`Install`	Scripts and other files for setting up the NAO robot.
`Make`	Scripts and project files for software development. `Make/<os/ide>` contains project files for a specific IDE or build system. `Make/Common` contains the shared part of the build system. It also contains scripts for deploying the code and downloading log files that are used by other tools. `Make/Hooks/installHooks[.cmd]` can be used to install git hooks that will automatically call the script `Make/$<$os/ide$>$/generate` after most git operations.
`Src`	All source files of the B-Human system.
`Util`	3rd-party code that is not part of the B-Human system.

Configuration File Search Path¶

All configuration files are searched along a path that contains directories that can depend on the name of a robot (separately for head and body, so mixing those is possible), the location where the robot is used (e.g. outdoor field vs. indoor field), and the scenario in which it is used (e.g. normal game vs. technical challenge):

Config/Robots/<head name>/Head
Config/Robots/<body name>/Body
Config/Robots/<head name>/<body name>
Config/Locations/<location>
Config/Scenarios/<scenario>
Config/Robots/Default
Config/Locations/Default
Config/Scenarios/Default
Config

In simulation, the name of both head and body is Nao. The current location and scenario are defined in the file Config/settings.cfg. They can also be changed while deploying the code to an actual NAO (cf. this section). Simulated robots will use the Default location and scenario unless they are changed in the startup script of a scene (cf. this section).

For the bush, the configurations Develop and Release are identical. That’s why the Xcode project does not offer a scheme to build the target in the configuration Develop. ↩
On Windows, see this website ↩
See this chapter ↩
Instead of Nao, you can also build Utils/deploy, which allows to directly deploy the code to a NAO robot, if it is already set up for deploying our software. ↩
On Windows, the first time starting such a file the SimRobot.exe must be manually chosen to open these files. Note that both on Windows and macOS, starting a scene description file bears the risk of executing a different version of SimRobot than the one that was just compiled. ↩
The script might instead automatically connect to the IP address that was last used for login or deployment. ↩