Nao tutorial 2: First module

The first tutorial focused about giving you a painless introduction to Nao's world. You turned the robot on, connected to him through the web interface and SSH, configured some parameters and learnt a bit about the most important files and folders.

Now, it is time for you to delve deeper into the subject, and the best way is to code and test your own example module. Nao has some good default applications that allow you to control his behaviour (like Choregraphe), but this is nothing compared with the freedom that compiling your own applications gives to you. Hence, you will now practice with the official SDK (section "Software/Download").

NOTE: This tutorial is targeted for version 1.10.10 of the SDK and OS. Older versions like 1.8.16 or 1.6.13 are not likely to work.

Getting everything ready

I guess that your testing environment is the same as in the previous tutorial, only with your Nao connecting via wifi now. Also, you will need to download some software from Aldebaran's webpage, but if you are reading this wiki, it's because you are connected to the internet (duh!). Remember to turn your robot off if it isn't already.

Official SDK

The guys from Aldebaran Robotics have an official SDK (Software Development Kit) available for registered users, on their webpage. Navigate to this link, enter your login info (you have it, right?), then click the "Software" and "Download" links.

Aldebaran's software download website.

You must download the last version of the Linux SDK (1.10.10 currently). After clicking on it, you have to scroll down the user license agreement, "I agree", and "Click here to proceed". Wait for the 162 MB file to download (it's called naoqi-sdk-1.10.10-linux.tar.gz). Extract its contents, and it will spawn a folder named naoqi-sdk-1.10.10-linux/. Move it to the location you like most.

Dependencies

A couple of Linux packages are needed to create and build your own applications. Luckily, this can be as easy as entering the following command in a terminal (Debian or Ubuntu only, folks):

sudo apt-get install build-essential cmake python-all libboost-all-dev libmpfr-dev cmake-curses-gui -y

Helloworld example in Naoqi

Introduction to the SDK

Open your naoqi-sdk-1.10.10-linux/ folder and take a good look at it. Two text files can be found at the root, README.txt and release-note.txt. Read both carefully. You can also explore the whole content, but there is no need to, as I will now enumerate the most important files and folders of the SDK:

• naoqi : a shell script located at the root of the folder. It will conveniently start Naoqi after setting all needed environment variables.
• toolchain-pc.cmake : this file must be fed to Cmake when you want to compile something for your local Naoqi (not for the robot).
• bin/flash-usbstick : another script, in this case for formatting an USB stick with a given version of Nao's OS.
• doc/index.html : local version of Aldebaran's official documentation. You won't need to go to the website anymore.
• modules/src/module_generator.py : Python application for generating your examples from a template. Very handy!
• preferences/autoload.ini : Configuration file that states which modules should be loaded by Naoqi at startup. Do never mix this autoload.ini with Nao's one!
• bin/ : this is where your Naoqi-compiled executables will be placed.
• lib/naoqi/ : this is where your Naoqi-compiled modules (libraries) will be placed.
• modules/src/examples/ : all pre-made examples can be found here, like Helloworld.

This is almost everything you should know about the SDK for this moment. The normal COA (course of action) when creating a new module is simple: you would usually run module_generator.py to generate a default module with pre-made code. You would then edit it according to your needs, use Cmake to generate the corresponding Makefiles, and use the latter ones to compile the code and build your module. Finally, you would start Naoqi to test it. Naoqi, included with the SDK, lets you create and test code without touching the real Nao. Obviously, not all functionality will be available when doing this.

Checking the code

I won't make you generate your own code yet. As this is your first time, we will use one of the available examples. Go to naoqi-sdk-1.10.10-linux/modules/src/examples/helloworld/, where 6 files await you. Only the ones with C++ code matter to you, that is, alhelloworld.h, alhelloworld.cpp and helloworldmain.cpp. Open them (any editor will do, like Gedit). helloworldmain.cpp is the least important and just creates an instance of the module, so you will almost never modify it.

The other two are the definition (.h) and implementation (.cpp) of the "ALHelloWorld" module itself. This module in question has only one function, "helloWorld()", that prints the message "Hello World!", and does nothing more (well, what did you expect?).

Programming for Nao focuses around modules. There are several default modules available that provide many utilities, like ALMotion (for moving the robot), ALMemory (for safe data storage and interchange), or ALLogger, which is used in the Helloworld example for message output. And of course, you can create your own. Modules communicate between themselves using proxies. A proxy is nothing more than an object that lets you call functions from other modules, passing parameters and such.

Graph that shows how brokers and modules work internally.

The other important concept is the broker. A broker is an executable that runs in the robot, listening on a given port for incoming commands (like a server). Brokers can load a list of modules at startup, and then manage the communication procedure. By default, the robot starts a broker called "MainBroker" that listens on port 9559, and loads the list of modules found in autoload.ini. You can create your own broker as well.

WARNING: If your module fails at runtime, it will make the broker it is associated with fail too. If the MainBroker fails the robot will lose motion and fall to the ground. You are advised to test your modules using your own broker.

Compiling

After introducing you to the inners of Naoqi, we are ready to compile for the first time. The SDK uses Cmake as its build system. Though it can look daunting at first if you were used to Make, it is incredibly easy to get it working if you know how. Also, think that the experience will serve you for many other Cmake-compiled programs.

The first thing you should do is to create a separate building directory, different from the source's one. This is a good approach for avoiding unnecessary confusion. So go and create a new build/ directory next to the 6 existing files. Now open a terminal, navigate to it and issue cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain> .., like this (mind the final two dots):

cmake -DCMAKE_TOOLCHAIN_FILE=../../../../../toolchain-pc.cmake ..

Toolchain files tell Cmake what to do exactly: which sources to compile, which compiler to use, where to save the build result... toolchain-pc.cmake is that file located at the root of the SDK that I told you about before, and is intended for compiling modules that will work in your PC running a local Naoqi. If everything went smooth, Cmake should have ended with "Configuring done. Generating done. Build files have been written to [...]", and the build/ directory will be now filled with content.

Among the contents you will find a Makefile. This sounds familiar to you, doesn't it? Hesitate not and issue:

make

NOTE: Additionally, you can append the parameter -jX to speed up the compilation, X being two times the number of cores or processors of your PC.

Hopefully you will get no compilation errors, and the process will end with a "[100%] Built target helloworld". Your compiled module should have appeared in naoqi-sdk-1.10.10-linux/lib/naoqi/, in the shape of a libhelloworld.so dynamic library (well, to be sincere it was already there, precompiled, but you can delete it and compile again with make to see that I don't lie).

Testing

The toolchain file was as neat as to place the library in the good location for Naoqi to load it. We just have to add its name to the naoqi-sdk-1.10.10-linux/preferences/autoload.ini file. Open it with any editor, and append this new line after the one that says "behaviormanager".

helloworld

Save and exit. We must run Naoqi now, using the script located at the root of the SDK directory. It will set some environment variables that Naoqi needs in order to work, and then run the main binary. A colourful wave of logging messages will welcome you. The last but one should say "INF: Registering module : ALHelloWorld". Leave this terminal as it is.

./naoqi

That's good. Naoqi correctly loaded our module, but, how do we test it? We will take advantage of the fact that Naoqi is cross-language; that is, applications can be coded in different languages but they will interoperate in a transparent way thanks to proxies. You can (and will) code your module in C++ and call its functions from a Python script. Return to the directory where the sources of the Helloworld example were, and open a file called test_alhelloworld.py. Fortunately, Python is very simple, and you won't need to master it. Lines 12 and 13 tell the proxy the IP and port where the broker containing our module (MainBroker) is listening on. Line 21 tries to create a proxy to our module, and line 31 tries to call the "helloWorld()" function.

Open a terminal here and run the test code (in case of error, refer to the last sections of this tutorial):

python test_alhelloworld.py

It should only take a couple of seconds and two lines of output for it to work. Now switch back to the terminal where you left Naoqi running, and take a look. Two new log lines should be there, stating "INF: New client broker: ALProxyBroker 127.0.0.1 54010" and "INF: MyModule: Hello World!". If you want to, edit alhelloworld.cpp, change the message, recompile and rerun Naoqi for more testing.

Module example in Nao

Working with the real robot instead of Naoqi is as easy as specifying a different toolchain file for Cmake, moving the compiled example to the /home/nao/naoqi/lib/naoqi/ folder of your Nao, and appending the name of your module to the /home/nao/naoqi/preferences/autoload.ini file.

Troubleshooting

You may run into annoying problems while developing for Nao (I certainly did), some easier to solve than others. I will try to explain how to fix the most common ones. If you have any questions regarding this subject or know of a different bug, feel free to send me an email describing it, and I will add it to this section. Just remember to try Google first!

Conclussions

---

Previous tutorial: Nao tutorial 1: First steps