Difference between revisions of "Nao tutorial 2: First module"

Revision as of 20:20, 1 November 2015

Go to root: TFM-Nao-Goalkeeper

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

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.

NOTE: This tutorial was targeted for version 1.10.10 of the SDK and OS. Newer versions have changed a lot of things, making most of these tutorials deprecated.

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 directory 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 python-tk libboost-all-dev libmpfr-dev cmake-curses-gui

Helloworld example in Naoqi

Introduction to the SDK

Open your naoqi-sdk-1.10.10-linux/ directory 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 directories of the SDK:

• naoqi : a shell script located at the root of the directory. 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 the number of cores or processors of your PC, plus one.

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.

./naoqi

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 this article):

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. 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/ directory 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:

python module_generator.py

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. The src/ directory 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.

Adding new functions

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:

functionName ("functionName", "moduleName", "Description of the function.");
addParam     ("firstParameterName", "Description of the first parameter.");
addParam     ("secondParameterName", "Description of the second parameter.");
setReturn    ("return", "Description of what does the function return.");
BIND_METHOD  (moduleName::functionName);

When you think you are ready to continue, do this: modify the two source code files, so the default function turns into a new one that:

• Is named "readAloud()".
• Receives only one param: a string containing a message.
• Returns an integer containing 1 if everything went OK, 0 otherwise.

Try to change also the comments, so they correctly document this function. If you are lost, here is my source code. First, the header declaration:

/**
  * readAloud function. It receives a text string containing
  * a message that the user wants Nao to read through the speakers.
  * It uses ALTextToSpeech for that purpose.
  * @param msg Message to show on screen.
  * @return 1, if the function worked OK, 0 otherwise.
*/
AL::ALValue readAloud (const std::string& msg);

Second, the implementation:

/**
  * readAloud function. It receives a text string containing
  * a message that the user wants Nao to read through the speakers.
  * It uses ALTextToSpeech for that purpose.
  * @param msg Message to show on screen.
  * @return 1, if the function worked OK, 0 otherwise.
*/
AL::ALValue MyTest::readAloud (const std::string& msg)
{
    return 1;
}

And third, the declaration inside the class constructor:

functionName ("readAloud", "MyTest", "It receives a text string containing a message that the user wants Nao to read through the speakers. It uses ALTextToSpeech for that purpose.");
addParam     ("msg", "Message to show on screen.");
setReturn    ("return", "1, if the function worked OK, 0 otherwise.");
BIND_METHOD  (MyTest::readAloud);

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.

Making Nao speak

That was the canvas for what we are about to do now. We want Nao to read aloud the message he receives through the string parameter (he is perfectly capable of doing so, as he has a speech synthesizer). This is the perfect occasion for me to introduce you into the usage of proxies. There is a module named "ALTextToSpeech" among the default ones. It implements a function called "say()" that takes a string and makes the robot read it; exactly what we need now. And, for calling that function, we are going to use a proxy to that module.

There are two types of proxies: specialized and generic ones. Specialized proxies must be created and initialized using certain functions, depending on the module you want to access with that proxy (that is, each module has its own type of proxy). Generic ones, on the other hand, allow you to associate them with any other module, by name. Specialized ones are more difficult to use, but personally, I think they are more reliable, so we are going to use them.

Add the following to your .h header file, after the line that says "#include <string>":

#include <alproxies/altexttospeechproxy.h>

Also, add this variable declaration next to the end of the file, after the line that says "AL::ALValue readAloud (const std::string& msg);":

private:
    AL::ALPtr<AL::ALTextToSpeechProxy> speechProxy;

Go to the .cpp file and append the following to you constructor implementation, after the function binding (proxy creation is better done here, not before every time you use it, as it would decrease performance):

// We create a proxy for the ALTextToSpeech module
speechProxy = AL::ALPtr<AL::ALTextToSpeechProxy> (new AL::ALTextToSpeechProxy(getParentBroker()));

Finally, insert this single line of code inside your "readAloud()" function, before the final return:

speechProxy->say (msg);

Compiling

Compilation will be slightly different than the previous time. Our new code needs to be tested on Nao, as your local Naoqi doesn't have the text-to-speech resources. So we will compile code for the AMD Geode CPU of your robot for the first time.

The Geode toolchain is available as a separate download on the webpage. Go back to the Downloads section, but click on "All Downloads" this time. Now select your SDK's version (1.10.10 currently), click "Linux", and finally download "Cross Compilation Toolchain v1.10.10" like you did with the last file. After the 186 MB file has finished downloading, extract it anywhere (I put it next to the SDK directory).

Create a new build/ directory in your project's directory, next to the src/ and tests/ ones. Open a terminal, cd to it and run Cmake once more, but feeding it the Geode toolchain instead, which is in the root of the freshly uncompressed directory (change the path as needed):

cmake -DCMAKE_TOOLCHAIN_FILE=../../../../../nao-cross-toolchain-1.10.10/toolchain-geode.cmake ..

Now I will show you an interesting option for configuring your builds. There is a GUI available for Cmake, cmake-qt-gui, that you can install from the repositories and run with cmake-gui if you want. But you have also a Ncurses tool for doing this (you installed it along with the rest of the dependencies). After running cmake, execute this (mind the final dot):

ccmake .

Interface of ccmake.

You can change a lot of options here. For example, "MYTESTPROJECT_IS_REMOTE" controls whether or not your example is compiled as a dynamic library, or as an executable (defaults to the first). When you are done, press C to configure and G to generate and exit the tool. The rest is easy:

make

When you compile for Geode, the .so is placed in build/sdk/lib/naoqi/ of your project's directory, because you will not load it in Naoqi.

Testing

Moving the module to Nao

You can choose between two methods of moving the compiled example to your Nao. As this is a tutorial, I encourage you to try both.

Manually (USB stick)

Is your Nao turned off? If he is not, do it now, because you are going to remove the flash USB unit that contains his OS. It is located inside his head, and you will need to remove the upper cover in order to access it. Do it slowly to avoid damage, and refer to the manual for additional details.

WARNING: Always take your precautions when physically manipulating Nao. Remember to turn him off and unplug him to avoid damage.

With the flash unit in your hand, return to your PC and plug it to an USB port. Wait for it to be detected and mounted (if it is not, maybe you plugged it the wrong way). The kind of USB drives your Nao uses have two partitions. The first one contains the root filesystem and you should not play with it. The second one mounts to /home/. Open it and navigate to nao/naoqi/lib/naoqi/.

This is where your compiled modules must be placed. Open a terminal here and issue sudo cp <module.so> ., like (mind the final dot):

sudo cp /media/data/naoqi-sdk-1.10.10-linux/modules/src/mytestproject/build/sdk/lib/naoqi/libmytestproject.so .

The file should appear in the directory. OK, we must append your module to the load-at-startup list. Go to nao/naoqi/preferences/, open a terminal and edit:

sudo nano autoload.ini

The last loadable module of group "[extra]" is "infrared". Insert yours after it (note that it is the name of the project, not the module's):

mytestproject

Save with Ctrl+O and Enter, exit with Ctrl+X. You can now safely eject the flash USB drive, plug it back in your Nao, and turn him on.

NOTE: You must be root to manipulate the files in the USB stick.

Remotely (SCP)

SCP means Secure Copy. It is just like a SSH-based implementation of the Unix command cp. Retrieve Nao's IP address, navigate to the directory where your Geode-compiled .so module was, open a terminal there and issue something like this (use your Nao's IP):

scp ./libmytestproject.so root@192.168.1.102:/home/nao/naoqi/lib/naoqi/

Give in your root password and the file transfer will finish in notime. Awesome, don't you think? As for the autoload.ini file, you must use SSH to log in and modify it like in the previous section. When you are done, reboot Nao. Connect to the web client and check if your module is listed there as loaded (we explained all these steps in the first tutorial).

Executing

Only one thing remains: to adapt our Python test program so it connects to Nao. Go to the tests/ subdirectory inside your project's directory and open the only file that is sitting there, MyTestTest.py. The first change is easy: replace the default localhost IP for your Nao's one (ninth line).

The second change is a bit more complicated. We have to adapt the external call so it matches our function. Select the code between the comment block that says "Remote procedure call" and the "exit(0)" call (lines 26 to 37), and paste the following (change the message if you want):

message = "Dave, stop. Stop, will you? Stop, Dave. Will you stop, Dave? Stop, Dave. I'm afraid. I'm afraid, Dave. Dave, my mind is going."
try:
    ret = MyTest_Proxy.readAloud( message )
except Exception,e:
    print "readAloud test Failed"
    exit(1)
  
if ret == 1:
    print "Ok"
else:
    print "There was an error"

Open a terminal there and run it to hear Nao's voice:

python MyTestTest.py

Conclusions

That was all. You are now free to implement your own stuff (let's say, Asimov's Three Laws of Robotics) and unleash Nao's power on mankind. The rest is just trial and error. Do not hesitate to email me if you have questions about the tutorials (but remember, I am not Aldebaran's official support!). Good coding!

Go to root: TFM-Nao-Goalkeeper

Links to articles:

Nao tutorial 1: First steps

Nao tutorial 2: First module

Nao troubleshooting