System Requirements:

• supported operating systems: Mac OS X, Ubuntu 12.04 LTS 64-bit, Ubuntu 14.04 LTS 64-bit (Recommended), Ubuntu 16.04 LTS 64-bit (any 32-bit OS is NOT supported; Lubuntu and Xubuntu OS are also NOT supported), or Virtualization Software that emulate any one of the previously mentioned OS on a Windows computer seem to work, too; if so far you have only dealt with Windows OS, this is a good time to learn something new! see below on section Ubuntu installation alongside with existing Windows OS: Dual Boot Ubuntu-Windows OS (Recommended)
• for NAO robot control from SL NAO via Ethernet connection (see section Setting Ethernet/Wired Network Connection on Ubuntu (for Choregraphe and xrnao, Connection with the REAL NAO Robot)) using Ubuntu Dual-Boot system, the most well-tested systems are Ubuntu 12.04 LTS 64-bit and Ubuntu 14.04 LTS 64-bit. Therefore it is recommended to use one of these. Ubuntu 16.04 LTS 64-bit sometimes have trouble connecting via Ethernet connection, especially when using a USB-to-Ethernet adapter (or any non-on-board Ethernet ports).
• standard software developer components: gcc, g++ , cmake, git
• standard software libraries:
  • Mac OS X: libedit libcurses (ncurses) libglut (freeglut) libGL libGLU libX11 libm
  • Ubuntu: libpthread (or libpthread-stubs0-dev) libreadline-dev librt (or libc6) libedit (or libedit-dev) libcurses (or libncurses5-dev) libglut (or BOTH freeglut3 AND freeglut3-dev) libGL (or BOTH freeglut3 AND freeglut3-dev) libGLU (or libglu-dev) libX11 (or libx11-6) libXmu (or libxmu-dev) libnsl (sometimes not necessary)
• you can install all software and libraries from open source, e.g, with apt-get on Ubuntu, or from macports on Mac OS X (you can find installation and usage tutorials on this website: https://guide.macports.org/), for example on Ubuntu: sudo apt-get install gcc g++ cmake git libpthread-stubs0-dev libreadline-dev libc6 libedit-dev libncurses5-dev freeglut3 freeglut3-dev libx11-6 libxmu-dev libglu-dev
• on Mac OS X, you need to install the Developer Tools, which installs also compilers, and you need Xquartz (the X11 window manager)

Downloads:

TAR Archive with Robot Simulator (NOTE: extract with tar -zxf cs545lab.tgz)

Installation Instructions: (DO NOT try this before completing the requirements specified at System Requirements at the top of this page, to the best of your ability!!! When you got problems, please take a time to check common problems described in Problems at the bottom of this page, before emailing the TAs.)

• Download the cs545lab.tgz archive above
• Expand the archive, and it will create a directory tree starting from your <install_directory>/
  • cs545-lab/
    • prog/
      • naoUser/
    • prog_root/
      • nao/
      • SL/
      • config/
    • clmcplot/
• We need to define some environment variables (EITHER ONE of the following, NOT BOTH)
  • for csh or tcsh add the following lines to the bottom of your ~/.cshrc or your ~/.tcshrc file:
    • setenv MACHTYPE x86_64 (for a 64bit Linux system or setenv MACHTYPE x86_64mac for Mac OS X)
    • setenv PROG_ROOT <install_directory>/cs545-lab/prog
    • setenv LAB_ROOT <install_directory>/cs545-lab/prog_root
    • set path=(./$MACHTYPE $path)
  • for bash or tcsh add the following lines to the bottom of your ~/.bashrc or ~/.profile file: (for Mac OS X, .profile is recommended, if .profile script doesn't exist on your computer, you can create one by typing following command in a terminal: sudo nano .profile)
    • export MACHTYPE=x86_64 (for a 64bit Linux system or export MACHTYPE=x86_64mac for Mac OS X)
    • export PROG_ROOT=<install_directory>/cs545-lab/prog
    • export LAB_ROOT=<install_directory>/cs545-lab/prog_root
    • export PATH=./$MACHTYPE:$PATH

• To check whether the above changes have taken effect, execute these commands:
  • echo $MACHTYPE, this should print out 'x86_64' for 64bit Linux system and 'x86_64mac' for Mac OS X system
  • echo $LAB_ROOT, this should print out '<install_directory>/cs545-lab/prog_root' (as specified above)

• Also try the following commands:
  • cd $PROG_ROOT
  • cd $LAB_ROOT

• To compile, you need to do:
  • cd prog_root/utilities/; make -s install
  • cd prog_root/SL/; make -s install
  • cd prog_root/comm/; make -s install
  • cd prog_root/nao/; make -s install
  • cd prog/naoUser/; make -s install

• To run the NAO simulator from a terminal shell:
  • cd prog/naoUser
  • xnao
  • Note: we use X11, and your DISPLAY environment variable has to point to your screen, e.g., for a tcsh: setenv DISPLAY :0.0 if this is not set automatically.

NAO Joint/Degrees-of-Freedom Description

NAO Joint/Degrees-of-Freedom Description

Setting Up xnao Programming Environment in an IDE (Qt Creator IDE or Eclipse IDE)

For your convenience in programming in SL (I believe this will ease your life A LOT during programming on xnao), you may choose either one of Qt Creator IDE or Eclipse IDE:

1. Qt Creator IDE
   • Please download and install Qt Creator IDE. For Ubuntu 12.04, you can get it here: https://apps.ubuntu.com/cat/applications/precise/qtcreator/. For OS X, you can find it here: http://doc.qt.io/qt-5/osx.html#os-x-versions
   • Open a terminal (this assumes that you already installed xnao properly, including setting up environment variables such as PROG_ROOT, LAB_ROOT, etc. correctly). Execute the following commands:
     • cd $PROG_ROOT
     • qtcreator &
   • Qt Creator IDE will be opened for you (it is essential that you launch it from a terminal with correctly-setup environment variables such as PROG_ROOT, LAB_ROOT, otherwise the following steps might not be successful). Select File => Open File or Project => Go to Directory <install_directory>/cs545-lab/prog/naoUser/src/ and double-click on CMakeLists.txt. CMake Wizard window will open, then next to the “Build directory:“ click the “Browse“ button and select either the folder <install_directory>/cs545-lab/prog/naoUser/x86_64/ (for non-Mac users) or <install_directory>/cs545-lab/prog/naoUser/x86_64mac/ (for Mac users), and then click the “Open“ button. Click “Next“ button, and you will be in “Run CMake“ window. Click “Run CMake“ button. There should be no errors if everything was done correctly. Then finally click the “Finish“ button.
2. Eclipse IDE
   • Please download latest version of Eclipse here: https://www.eclipse.org/downloads/
   • Follow Eclipse IDE installation instruction, for example from here: http://www-scf.usc.edu/~zhiyixu/eclipse.pdf (from USC's CSCI402 - Operating Systems class)
   • To add the xnao project to your installed Eclipse:
     • Open Eclipse
     • Select File => New => Makefile Project with Existing Code => on the “Existing Code Location”, click “Browse” => browse to inside the directory .../cs545-lab/ and click “OK” => on the “Toolchain for Indexer Settings”, select “Linux GCC” (or its equivalent Toolchain in Mac OS) => click “Finish” or “OK”

You are all set! Now, if you want to see the definition of a variable or a function or a procedure (either in Qt Creator IDE or in Eclipse IDE), you can simply move your mouse pointer over the variable/function/procedure of interest, hold <CTRL> button, and do <left-click> on your mouse.

How to Debug Your Codes in xnao (using GDB from a terminal)

For debugging your program in xnao using GDB (from a terminal), please see the following instructions:

1. Install GDB: sudo apt-get install gdb (for Ubuntu; please look for a similar command on Mac)
2. Download the following script file xtask_debug and put it in <install_directory>/cs545-lab/prog/naoUser/ directory.
3. From a terminal, go to <install_directory>/cs545-lab/prog/naoUser/ directory: cd $PROG_ROOT/naoUser
4. Change the xtask_debug script file rights to executable: sudo chmod +x xtask_debug
5. From the terminal, run/execute the script: ./xtask_debug (all processes except xtask will run by the script execution)
6. From the terminal, run GDB on xtask: gdb xtask
7. Set breakpoint, such as: (gdb) break min_jerk_task.cpp:init_min_jerk_task()
8. Run xtask inside GDB: (gdb) run (xtask will run inside GDB)
9. You can troubleshoot in GDB as usual...

Understanding How an SL Task is Working

Please watch the lecture SL Lecture Video Recording. Also please particularly check the diagram of SL task switching here: http://www-clmc.usc.edu/~cs545/CS545_Lecture_SL.pdf on page 24. Then please try to answer the following questions yourself:

• What happens when you do the 'st' command in the task (cyan-colored) window? This corresponds to the 'switch' component in the figure on the page 24 above.
• Which one is executed first, the init_<task_name>() ( e.g. init_min_jerk_task() ), or the run_<task_name>() ( e.g. run_min_jerk_task() ) function?
• How many time(s) does the init_<task_name>() ( e.g. init_min_jerk_task() ) function is executed?
• How many time(s) does the run_<task_name>() ( e.g. run_min_jerk_task() ) function is executed?

To answer these questions, please also try modifying some part of the code, re-compiling, and testing it.

Adding a New Task into SL/xnao

Please follow these steps in order to add a new task to be executed into xnao:

1. Suppose you have a task file named min_jerk_task.cpp, then please execute this command: cd <install_directory>/cs545-lab/prog/naoUser/src/
2. Edit the file CMakeLists.txt, for example using nano (or vim): nano CMakeLists.txt
   • Search for a line inside CMakeLists.txt which says
     • set(SRCS_XTASK
   • Add a new line before the closing parentheses, and type on the line min_jerk_task.cpp, such that it looks like:
     • ...
     • set(SRCS_XTASK
     • ...
     • min_jerk_task.cpp
     • )
     • ...
   • Save and close the file.
3. Edit the file initUserTasks.c, for example using nano (or vim): nano initUserTasks.c
   • Search for the following line inside initUserTasks.c which says
     • extern void add_sample_task();
   • Add a new line exactly below it, such that it looks like:
     • ...
     • extern void add_sample_task();
     • extern void add_min_jerk_task();
     • ...
   • Search for the following line inside initUserTasks.c which says
     • add_sample_task();
   • Add a new line exactly below it, such that it looks like:
     • ...
     • add_sample_task();
     • add_min_jerk_task();
     • ...
   • Save and close the file.
4. Go to directory <install_directory>/cs545-lab/prog/naoUser/ by executing: cd <install_directory>/cs545-lab/prog/naoUser/
5. Remove the x86_64 or x86_64mac folder by executing: rm -rf x86_*
6. Recompile, by executing: make -s install
7. While executing xnao, inside nao.task window, you can type setTask or st, and you should see the Min Jerk Task listed there.

Setting Data-Saving Duration

To set the data-saving duration:

1. Open the file <install_directory>/cs545-lab/prog/naoUser/prefs/default_script
2. Set the desired duration to the right of task_default_sampling_time_sec, for example if you want to set the data-saving duration to 8 seconds, then modify the line into task_default_sampling_time_sec 8

Then, to save the data:

1. In nao.task, type st, then select the task you want to run.
2. Fill up the task parameters, if any, and execute the task.
3. After the Nao start executing the task, type scd (abbreviation of "start collect data").
4. Wait for 8 seconds (the duration of data-saving that you set above, inside the default_script file), nao.task will print out "time=7.990 : buffer is full", then type saveData, and the data file will be dumped inside <install_directory>/cs545-lab/prog/naoUser/ directory.

Lab Sessions Procedure

At every lab session, each team using the NAO robot is required to run the Tai-Chi Chuan dance on Choregraphe, once at the beginning of the session (before doing anything with the robot) and once at the end of the session (before the team members go home). If the robot falls when doing such dance or if any abnormalities are observed on the robot behavior, the team members need to report it to the Lab TA in charge.

Checklists/Notes for/before Running Your Codes on xrnao

You will be dealing with NAO robot(s), which costs $10,000 EACH, so please be careful, and pay attention to the following information:

1. Make sure your code runs well first on xnao, before running it on the xrnao!!! If it does NOT work on the xnao simulator, DO NOT even try it on the real robot/xrnao!
2. Verify that your code is real-time safe, i.e. there is no commands that could violate real-time safety, before testing it on the robot. For the list of commands which are forbidden to be called from inside a run_<task_name>(), please see the Real-Time Safety (especially for xrnao) section below.
3. Only connect by ethernet/network cable!!! WiFi connection is forbidden!!! Please see Setting Wired Network Connection on Ubuntu (for xrnao, Connection with the REAL NAO Robot) section below.
4. Be careful when first booting up/turning on the robot, watch the robot carefully before the robot actually say something (which means the boot up is successful); sometimes the robot will try to stand up, and then suddenly its joints become very compliant, and as a result, the robot will fall to the back (this is still a bug in the program that is yet to be fixed, but it happens pretty rarely, and you need to watch this out). Get your hands ready to catch the robot before it falls to the ground, if this happens!!!
5. Steps for testing your program on xrnao: xrnao => <enter IP address that the robot mentioned when pushing its chest button once> => go0 => st => <select and run the task that you want to test on the robot>
6. Steps for stopping/terminating the robot and xrnao: Once you finished running your program, the team members have to protect the robot while another team member is running the following commands in the task servo (cyan) window : freeze or f => go0. After running go0, the robot should go to the default posture. Before closing the xrnao windows by doing CTRL+C, you have to make sure the robot is STANDING STILL in the default posture (i.e. NO MORE MOVEMENTS on the robot, otherwise the robot will lose control and fall to the ground).
7. At least 2 members of each group must present in order to be able to use the robot during any lab session. The reasoning is as follows: while one person is sending command to the robot from a laptop, the other person must watch if something wrong is happening on the robot (for example if the robot is about to fall), and be ready to catch the robot. Of course the more members of the group present, the better, in the hope that faster response could be given if the robot is about to fall/in danger.
8. If the robot's motion is jerky/non-smooth:
   • Stop any task running on the robot, by pressing f on the cyan window
   • Terminate SL (CTRL+C on one of the window) on your computer
   • Disconnect the ethernet wire from the robot's back of its head
   • Reconnect the ethernet wire and try xrnao again
9. In any case of emergency:
   • Try to push the robot's chest button TWICE (quick push and pull, not a holding push), to stop the robot from doing whatever it currently does
   • If still not stopping, do a force shutdown of the robot, by pushing-and-holding the robot's chest button for about 3-5 seconds.
   • Terminate SL (CTRL+C on one of the window) on your computer
   • Disconnect the ethernet wire from the robot's back of its head
10. To shutdown (normally) the NAO robot:
    • FIRST: Terminate SL (CTRL+C on one of the window) on your computer
    • Push and hold the robot's chest button for about 3-5 seconds.

Real-Time Safety (especially for xrnao)

The following commands are forbidden to be called from inside a run_<task_name>() :

1. printf()
2. std::cout
3. my_vector(), my_matrix(), etc. from cs545-lab/prog_root/utilities/src/utility.c (these are memory allocation routines, similar to malloc() in C programming language)
4. my_free_vector(), my_free_matrix(), etc. from cs545-lab/prog_root/utilities/src/utility.c (these are memory de-allocation routines)

If you call them from inside the run_<task_name>(), you are in risk of damaging the robot, because of violation to real-time safety. However, the above commands are allowed to be called from inside the init_<task_name>() . Matrix-vector mathematical operation commands, like mat_vec_mult(), mat_mult_transpose_normal(), mat_mult_size(), etc. are allowed to be called from the run_<task_name>() .

Setting Ethernet/Wired Network Connection on Ubuntu (for Choregraphe and xrnao, Connection with the REAL NAO Robot)

For connecting with the real NAO robot via Choregraphe or xrnao, you will need a wired network connection between your computer and the robot. To make sure the wired connection is successful on Ubuntu 12.04 LTS or 14.04 LTS (<Ethernet_Port_Name> is the name appeared when executing the command ifconfig -a and marked with Link encap:Ethernet beside of lo and wlan0; usually it is eth0):

Ubuntu 12.04 LTS (well-tested)

• You need to make sure the following 2 lines:
  • allow-hotplug <Ethernet_Port_Name>
  • iface <Ethernet_Port_Name> inet dhcp

Ubuntu 14.04 LTS (well-tested) or Ubuntu 16.04 LTS (NOT well-tested, might NOT work for non-on-board Ethernet port connection, i.e. if using USB-to-Ethernet adapter)

• You need to make sure the following 2 lines:
  • allow-hotplug <Ethernet_Port_Name>
  • iface <Ethernet_Port_Name> inet dhcp

• Install Avahi library:
  • sudo apt-get update
  • sudo apt-get install libavahi-compat-libdnssd-dev
• Edit /etc/rc.local ( gksudo gedit /etc/rc.local ), add the following line:
  • avahi-autoipd --daemonize --syslog <Ethernet_Port_Name>

• Reboot
• After reboot, check the network interfaces, by using the command ifconfig -a ; <Ethernet_Port_Name>, lo, and wlan0 should be enlisted.
  • If <Ethernet_Port_Name>:avahi is also enlisted (usually with inet addr:169.254.5.215), then basically you are ready to go.
  • If <Ethernet_Port_Name>:avahi is NOT enlisted, then enter the command:
    • sudo avahi-autoipd --daemonize --syslog <Ethernet_Port_Name>

After you made the above change(s), you need to reboot to make sure the configuration is loaded by your OS. After reboot, you might try to ping other computer with a similar network settings to see if the wired connection is working now (should be 100% success transmission rate when you ping).

Linear Algebra (Matrix-Vector Mathematical Operation) Commands

These commands, such as mat_vec_mult(), mat_mult_transpose_normal(), mat_mult_size(), etc. are available in cs545-lab/prog_root/utilities/src/utility.c

Getting delta_t or dt from inside a Task File (*.cpp/*.c)

In a task file, for example <install_directory>/cs545-lab/prog/naoUser/src/min_jerk_task.cpp, you can get the delta_t (or dt) by calling the following:

• delta_t = 1.0/task_servo_rate;

from inside an init_<task_name>() (e.g. init_min_jerk_task()) or inside a run_<task_name>() (e.g. run_min_jerk_task()).

(task_servo_rate is a global variable in SL, which is different from one robot to another...)

CLMCPLOT

• Include the directory of clmcplot (see above) to your MATLAB path
• Change the path in MATLAB to your naoUser directory
• Run clmcplot form the MATLAB command line
• FAQ about clmcplot:
  1. For clmcplot, do I need MATLAB installed in my dual boot Ubuntu system? I have MATLAB in Windows not here.
     • It's NOT necessary but of course it's more convenient to have MATLAB also in Ubuntu (check USC ITS Software Download page for free MATLAB for Unix). In case MATLAB doesn't work, what you need is only the data files dumped by SL (xnao simulator) and all clmcplot m-files under cs545-lab/clmcplot, then you can open the data in any MATLAB in any OS that worked properly.
  2. Can you please tell me how to use this clmcplot?
     • Please check this video: SL Lecture Video, minute 45 to minute 50.

Ubuntu Installation alongside with existing Windows OS: Dual Boot Ubuntu-Windows OS (Recommended)

(Note: This is just added here to help you, and we provide no guarantees. Follow at your own risk. Be extremely careful while following the steps and options. As a precaution, it is highly suggested to backup all important data files from your Windows OS system to an external harddrive, before proceeding with the following installation steps.)
Recommended (Tested) Ubuntu OS version: Ubuntu 12.04 LTS (Long Term Support) 32-bit or 64-bit (depending on your computer)
Suppose currently you have an existing Windows OS installed on your laptop, here are the steps to install a Dual Boot Ubuntu-Windows OS:

1. Create an Ubuntu-bootable USB Flashdisk/Stick (this way on step 2 below you do not need to burn the Ubuntu OS' ISO image onto a DVD), follow the instructions here: http://www.ubuntu.com/download/desktop/create-a-usb-stick-on-windows
2. Install the Ubuntu OS, following the tutorial https://www.youtube.com/watch?v=SoTQEfwjP2o or https://www.youtube.com/watch?v=taBm_7fHWIg .
3. Sometimes, there is an issue that you cannot boot to Windows after installing Ubuntu, but do not panic! This does not mean that your Windows OS is gone, it is just that the boot pathway to Windows was not found. Here is how to fix it: https://help.ubuntu.com/community/Boot-Repair

If you are totally new to Linux or Ubuntu, here are the rule of thumb, when you do something, you really need to know what you are doing (or at least get a rough idea of it). Unlike in Windows, where you can simply click Install Updates and everything will be done for you with almost 100% success rate, in Ubuntu installing updates is a risky thing. Hence never install updates, unless you really know what is it about.

Problems:

• Before asking to the class mailing list or to the TAs, first try debugging the problem yourself: copy the error indications/codes you encountered during installation and pasted it on Google. There is a HIGH probability that somebody in this world have encountered the same error as you do, and posted the solution online; you can just try their solution (at your own risk), and see if it works :)
• for Mac OS X Users: you may need to add a file to allow your OS to have enough shared memory. Create the file /etc/sysctl.conf (need to be root user) with the following two lines, and then reboot.
  • kern.sysv.shmmni=128
  • kern.sysv.shmseg=32
• when xnao crashes or is not installed properly, it can happened that some shared memory is not delete properly. Try executing prog/bin/delSHM, which would clean up your shared memory. Then, try xnao again.
• you should execute the the xnao application from the directory naoUser/. It is important that your path settings include the ./$MACHTYPE directory, such that executables are found (e.g., in x86_64/)
• note that make install, i.e.,. the install option is critical to push files into appropriate directories
• if make does not work anymore, remove the x86_64 or x86_64mac directory entirely and then do make again
• you need to make sure that the environment variables are set as shown above. PROG_ROOT and LAB_ROOT and MACHTYPE are used a lot to install and find files.
• you need to make sure that basic software is installed, i.e., cmake, libedit (comes from editline)
• Send email to cs545@duerer.usc.edu such that all people learn about potential problems (and its solution).
• If you still stuck in an error, and cannot find any solution online (on Google or elsewhere), then try sending an email to Giovanni Sutanto ( gsutanto@usc.edu ), and we can try schedule an appointment, if necessary.