Skip to content

Initial Setup

To give you a first idea how to work with the B-Human Code Release, this chapter will lead you through the first steps. You will get a general overview over the structure of our code, setup your IDE, execute the B-Human software in our simulation SimRobot, and also learn how to deploy the software on a real robot, if you have one available.

For the latter, 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.

Please read this tutorial carefully and follow it very closely at each step, as small mistakes might lead to errors that can be hard to understand for beginners.

Let's start by setting up your development environment!

Setting up the Development Computer

This section describes which software must be installed on a computer to run the B-Human software. 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.

  • Microsoft Windows 10 64 bit Version 21H1
  • Microsoft Visual Studio Community 2022 Version 17.0.0. Installing the workload Desktop development with C++ (including the packages MSVC v143 - VS 2022 C++ x64/x86 build tools, Windows 10 SDK 10.0.19041.0, and C++-ATL for latest v143 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). The required steps change occasionally and also depend on the previous state of the system and whether the WSL is used for other purposes. You should therefore consult Microsoft's documentation whenever you set up WSL for B-Human on a new Windows installation.

    • Ubuntu 22.04 must be selected as default distribution. Currently, Ubuntu 22.04 must be installed via the Microsoft Store.
    • That distribution should use WSL version 1 due to frequent Windows file system access (see here and here).

    • Without an existing WSL installation, the following command installed the correct distribution at the time of the 2023 code release:

      wsl --install -d Ubuntu --enable-wsl1

    • In that distribution, root must be the default user account. This can be achieved by pressing Ctrl+C when being prompted for a user name during installation of the distribution.

    • Packages need to be installed using the following commands in a Windows Command Prompt:

      wsl apt update
wsl apt -y install astyle ccache clang cmake llvm mold net-tools ninja-build pigz rsync xxd

    • No other command called bash (e.g. from Git or Cygwin) may be in the search path (as defined by the PATH environment variable) before the WSL bash.

  • macOS 13.5 (Intel or ARM)
  • Xcode 15.0
    • Xcode must be executed at least once to accept its license and to install its components.
  • CMake 3.26.3
    • Use a "macOS 10.13 or later" .dmg from here or install a cmake that can be found in the $PATH (e. g. via Homebrew).
  • A 64-bit Linux, e.g. Ubuntu 22.04 LTS

  • The following packages (here for Ubuntu 22.04 LTS):

    sudo apt install ccache clang cmake exfatprogs git graphviz libasound2-dev libbox2d-dev libgl-dev libqt6opengl6-dev libqt6svg6-dev libstdc++-12-dev llvm mold net-tools ninja-build pigz qt6-base-dev rsync xxd

  • (optionally) CLion 2019.3 or newer

Cloning the Repository

As the B-Human repository uses submodules, it must be cloned using git clone --recursive. Downloading it as zip or tar.gz does not work.

On macOS, the working copy must be either located outside of folders protected by macOS (e.g. Desktop, Documents, Downloads, etc.), or you have to grant full disk access to /bin/bash.1

All paths mentioned in this documentation will be relative to the main directory of the working copy.

Setting up the Working Copy

Cloning the Repository

As the B-Human repository uses submodules, it must be cloned using git clone --recursive. Downloading it as zip or tar.gz does not work.

On macOS, the working copy must be either located outside of folders protected by macOS (e.g. Desktop, Documents, Downloads, etc.), or you have to grant full disk access to /bin/bash.1

Creating Project Files / Compiling the Code

Run Make/Windows/generate.cmd and open the solution through the link Make/Windows/B-Human.lnk in Visual Studio. Select the desired configuration (Develop is a good start) and build one of the targets mentioned in this section3.

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.2

When building for the NAO (always Intel code), running the target will open a dialog to deploy the code to a robot (cf. this section). 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.

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.

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

  • Activate Xcode|Preferences|Text Editing|Editing|Automatically trim trailing whitespace
  • Activate Xcode|Preferences|Text Editing|Editing|Including whitespace-only lines
  • 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
  • Activate Edit|Format|Spelling and Grammar|Check Spelling While Typing

Run Make/Linux/generate to generate CMake caches.

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

Run Make/Linux/generate -c to generate CLion project files.

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

Setting Up the Git Hooks (Optional)

For contributing members of the B-Human team, it is recommended to use the provided hooks as part of their Git workflow.

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 to update the project files.

Additionally, the B-Human project offers pre-commit hooks that require a Python 3 installation. These scripts can run automatically before every commit to the repository to detect and fix some incorrect code formatting.

Run pip install pre-commit to install the framework for pre-commit hooks.

Run pre-commit install --install-hooks --overwrite inside the root folder of the B-Human repository to install the Git hook scripts.

Targets and Configurations

The B-Human project consists of the main build targets SimRobot, Nao, 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.

The following table lists the top-level build targets of the B-Human system.

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.
Nao The code is built to run on the NAO.
Tests Some unit tests. On macOS, this target is available by selecting SimRobot and then switching to Xcode's Tests Navigator.

Effects of the different build configurations are shown in the following table. SimRobot represents everything in the simulation except for SimulatedNao.

without assertions (NDEBUG) debug symbols (compiler flags) debug libs4 (_DEBUG, compiler flags) optimizations (compiler flags) debugging support5
Release
  Nao ✓ ✗ ✗ ✓ ✗
  SimulatedNao ✓ ✗ ✗ ✓ ✓
  SimRobot ✓ ✗ ✗ ✓
Develop
  Nao ✗ ✗ ✗ ✓ ✓
  SimulatedNao ✗/✓ ✗/✓ ✗ ✗/✓ ✓
  SimRobot ✓ ✗ ✗ ✓
Debug
  Nao ✗ ✓ ✓ ✗ ✓
  SimulatedNao ✗ ✓ ✓ ✗ ✓
  SimRobot ✗ ✓ ✓ ✗

In Debug, the code compiled for the robot (target Nao) is actually too slow to be used, i.e. motions will stutter. In Release, that code does not support debugging, which means that SimRobot cannot connect to a robot running it. In Develop, the library SimulatedNao is a mixture of debug and release code. The interface code for the simulator is optimized, while the robot code generally is not. However, some of the robot code would run extremely slow without optimization. Therefore, a few parts are also optimized and cannot be debugged.

Directory Structure

If you did each step as stated above, you should now have installed an IDE based on your operating system, and the repository should exist in an unprotected directory within your local file system. To get familiar with the structure of this directory, we explain what each subdirectory contains below:

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). Here you can also find the neural networks used in our software.
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.
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 scene description file (cf. this section).

Next steps

Now you should be ready to run our code. Click here to find out how that works!

  1. This is only relevant for the deploy dialog, which cannot be run directly from Xcode otherwise. ↩↩

  2. Newer versions of Xcode require to activate Rosetta under Product|Destination|Destination Architectures and then select Product|Destination|My Mac (Rosetta). ↩

  3. 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. ↩

  4. On Windows, see this website ↩

  5. See this chapter ↩

Last update: February 16, 2024