Better NAO than never (NAO tutorial part 1)

Lessening the pain in the ass, one step at a time :)

NAO Linux C++ development cheat sheet / tutorial, Part 1

Preamble to this whole series of tutorial posts

I'd like to thank Jane for hosting these posts on her blog, and Dimitri Merejkowsky from Aldebran, for his detailed feedback.

These posts start slow, but they get more technical later. The first part (which you've started reading) explains how to set up the C++ development environment for NAO under GNU/Linux. The second post gently introduces the build tools and a simple module. Starting from the third post, I discuss some more detailed aspects of C++ programming, and the code gets too large to be entirely pasted and explained in a blog post, and needs to be hosted elsewhere. Post 4 is still being written, but I will naturally need to make an even more drastic selection of what to explain and what to leave as an exploratory exercise for you, adventurous reader. Generally, I advise side-reading a lot of documentation(Aldebaran doc, Boost doc, C++ FAQ Lite, etc), other tutorials, and experimenting by yourself.

I assume development for NAOqi 1.14.2 on a linux host, with a robot at IP 192.168.1.11 (or something like that, it may vary a bit); adapt the examples to your own configuration. When examples depend on the Linux distribution, I give examples for both Ubuntu 12.04 LTS, which Jane is using, and Archlinux, which I use.

I assume that you are logged in Linux with the account that you want to use to develop, and that this user has the rights to at least install new software (on Ubuntu, that means that typing sudo apt-get should not tell you "operation not permitted").

You also need a minimal knowledge of the command line: know where you are (pwd) and where your files are, navigate to a directory (cd), create a directory (mkdir). I'll take you from there :).

Know the tools

NAOqi is a program that runs on the robot (it can also run on the computer and communicate with naoqi on the robot, but let's forget about that for now). It manages the loading of modules, communication between modules, and acts as the higher-level interface with the hardware.

qiBuild is a program that runs on the development computer. It's the most important build tool for NAO developers: you use it to configure a project, compile it and deploy it on the robot.

Qiuild can configure projects for various robots (Atom or Geode NAO) or to run on a separate computer. For that, it uses CMake, wich is a cross-platform and multi-platform meta-build tool. 

You need to give qibuild a toolchain name to let it know which set of tools to use to build your project. You typically will have a toolchain that contains a compiler and a linker configured for the architecture of your robot (Linux on 32 bit Intel Atom or AMD Geode).

We will also deal a little with common Unix tools like bash, ssh, scp...

Now I'll explain all this in more details.

Toolchain and environment setup

First, install some necessary stuff (some of it might already be installed):

GCC, CMake

Ubuntu:
sudo apt-get install gcc cmake
Archlinux:
sudo pacman -S gcc cmake

Python 2

Ubuntu:
sudo apt-get install python
Archlinux:
sudo pacman -S python2

The rest

You may also want to install QT Creator as it's the IDE recommended by Aldebaran (the recommended way is to use the installer available on the Qt website, or if you can't, you can use the older version from the Ubuntu repositories with sudo apt-get install qtcreator on Ubuntu.).

Then, you have to download the following files from the Aldebaran website (here with a developer account):

• NAOQI C++ SDK 1.14.2 for the architecture of your Linux development machine (32 bits or 64 bits). If you don't know if your kernel is 32 or 64 bit, type uname -m at the command line. If it replies with x86_64, you are using a 64 bit Linux. If it replies x86, 32 bit. If something else, you're kinda stuck as Aldebaran does not provide toolchains for other architectures.
• If your architecture is 64 bits, you may need to install some extra libraries for the cross-compilation to work (Dimitri from Aldebaran tells me that you no more need that, but it can't hurt). 
• On Ubuntu, from the command-line, you can write:
  sudo apt-get install gcc-multilib libc6-dev libc6-i386
• On Archlinux: sudo pacman -S gcc-libs-multilib
• NAOQI C++ Cross Toolchain 1.14.2 Linux 32 bits for your NAO (either NAO 3 (Geode) or NAO 4 (Atom))
• qiBuild -- There is only one choice here, but actually it's maybe not the best one :). You're better off with the development version of qiBuild that's on Github, because the one on the Aldebaran website has happened to be two years old and lack features, by the past.
• To get the latest development version of qibuild, there are several ways:
• (prefered method) install git (Ubuntu: sudo apt-get install git) and run:
  cd ~/nao/devtoolsgit clone git://github.com/aldebaran/qibuild.git
• (less good because keeping qibuild up to date is more difficult that way) download the zip file and unzip it in ~/nao/devtools
• Archlinux users, there is an AUR package, if you prefer.

Then extract these files in convenient locations. You can often do that with graphical tools, otherwise, do the following on the command line:

• If you have not already made one, you should create a directory for your NAO stuff: 
• mkdir -p ~/nao/{devtools,workspace}
• Navigate to you downloads folder, e.g. 
• cd ~/Downloads
• Extract all the development tools that we just downloaded, for instance in ~/nao/devtools: 
• if you have downloaded the zip archive of qibuild, unzip master.zip -d ~/nao/devtools
• tar xzf naoqi-sdk-1.14.2-linux??.tar.gz -C ~/nao/devtools
• tar xzf linux??-nao-atom-cross-toolchain-1.14.2.tar.gz -C ~/nao/devtools
• Install qiBuild (Ubuntu instructions):
• mkdir -p ~/.local/bin
• We need to add that directory to the $PATH environment variable, as the qiBuild binaries will be installed there. We first record that in the profile file, that is loaded at each login: echo "export PATH=\$PATH:$HOME/.local/bin" >> ~/.profile
• Now, to get the effect of that for the current login session, you can log out and in again. You can also just type export PATH=$PATH:$HOME/.local/bin in your command line to get the same effect for that terminal only
• cd ~/nao/devtools/qibuild
• ./install-qibuild.sh
• Now, try typing qibuild. If bash responds with qibuild: command not found, then there is a problem: either qibuild did not install to ~/.local/bin (ls ~/.local/bin), or ~/.local/bin is not on $PATH (echo $PATH).
• For Archlinux only (and only if you are not using qiBuild 2 from the github repo): use sed to replace all instances of " python " by " python2 " in ~/.local/bin: find ~/.local/bin/q* -type f -exec sed -i 's/python /python2 /g' {} \;
• Configure qibuild:
• cd; qibuild config --wizard
• You should normally choose:
  - Unix Makefiles,
  - QT Creator, followed by y

That should be it, basic stuff is now installed. Time to configure that toolchain we just downloaded.

qiBuild toolchain and workspace preparation

cd ~/nao/devtools

Now, let's say we have two robots, one with an Atom head and one Geode head. We have dowloaded and extracted both linux64-nao-atom-cross-toolchain-1.14.2 and linux64-nao-geode-cross-toolchain-1.14.2 in ~/nao/devtools. We want to make both toolchains available to qibuild. That would be those two lines:

qitoolchain create atom ~/nao/devtools/linux??-nao-atom-cross-toolchain-1.14.2/toolchain.xml

qitoolchain create geode ~/nao/devtools/linux??-nao-geode-cross-toolchain-1.14.2/toolchain.xml

Add --default to one of the above commands to make that toolchain the default one.

Here, we are giving each chain a short name that is easier to remember: "atom" and "geode". You can change those names, delete toolchains, and so on using the qitoolchain program (qitoolchain --help). For instance:

qitoolchain list # lists all toolchains

qitoolchain info atom # more info about the toolchain with nickname atom

qitoolchain remove geode # deletes the toolchain with nickname geode

With toolchains setup, we now only need to make a workspace. It's a directory that contains several projects. It contains some configuration information for all these projects too, in a folder called ".qi".

mkdir ~/nao/workspace

cd ~/nao/workspace

qibuild init --config atom

The last command makes that ".qi" folder, so ~/nao/workspace is now a qiBuild workspace. You can see that the folder is now a qiBuild workspace by typing ls -a, which reveals the .qi folder. The --config atom part is optional, it just makes the "atom" toolchain the default one.

Done! Now, let's copy a sample project from the SDK folder into our workspace to test it out:

cp -R ~/nao/devtools/naoqi-sdk-1.14.2-linux??/doc/examples/core/helloworld ~/nao/workspace

cd ~/nao/workspace/helloword
qisrc add .

We try to configure and compile it for our Atom head NAO:

qibuild configure -c atom

qibuild make -c atom

No error? Good. 

In the next part, we'll do our own C++ module that runs on the robot :D