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.
- 1 Getting everything ready
- 2 Helloworld example in Naoqi
- 3 Module example in Nao
- 4 Troubleshooting
- 5 Conclussions
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.
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.
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.
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 python-tk 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.
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.
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:
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).
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".
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.
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):
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. Anyway, you can stop it with Ctrl+C.
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. So, for making it more interesting, we will generate our own custom module this time.
Generating the code
Go to naoqi-sdk-1.10.10-linux/modules/src/, where module_generator.py lies. Run it:
A window will appear asking you for some data needed to create the new module. Enter any data you like, I chose "MyTestProject" as project name, "Me" as author name and "MyTest" as module name. Several modules can be created by entering their names in this last field, separated by spaces. Click "Generate" and, when prompted to quit, "Yes". A new directory called as your project name will be created there.
Open it. Folder src/ contains the source code of your module(s). tests/ contains the Python example(s) that will let you test everything. This differs not much from the Helloworld example, as you can see.
Modifying the code
Open the two main sources, mytest.cpp and mytest.h. The header contains the definition of your module (which is a C++ class), now containing only the default constructor, destructor, and a "dummyFunction()" method. You can change the comments or add new ones, to make the documentation match your purposes. And in a real project, you should.
The .cpp file is the implementation of the previous definitions. The comments in this file are the same than in the previous. There are two things here that I want you to see: the first one is that the "dummyFunction()" method (whose name you should change) is just a test function that receives a text string with a message and prints it.
The second one is the way in which you should "declare" new functions for Naoqi to work well with them. If you do this, your code will integrate flawlessly with the rest of the Naoqi framework. Remember that you could see the loaded modules from the web interface, knowing exactly which functions and for what purpose did it have available? That is only one of the many advantages.
Each time you create a new function, you should "declare" it inside the module's constructor. If you go there you will see that "dummyFunction()" was defined that way. The procedure is easy: after coding the function, you append a call for "functionName()" inside the class constructor, declaring its name and goal. Then you call "addParam()" as many times as needed, until you have declared every parameter your function receives. After this, you set (optionally) the return value with "setReturn()". Finally, you apply all this data and bind it to you function, by calling the macro "BIND_METHOD()". Example:
NOTE: When adding or changing stuff in your code -even comments-, remember to change it in both files (.h and .cpp) so they always match.
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!
Python fails to run
Cmake fails to run
Can't compile my module
Nao doesn't load my module
Proxy fails to connect
How to flash Nao
Previous tutorial: Nao tutorial 1: First steps