Getting Started

Setting up in a Virtual Machine

To setup rUNSWift on a VM, you may use the provided VM image on the rUNSWift server. If you would like to setup your own VM, see the instructions under Manual Setup.

Manual Setup

Setting up your OS

The OS that currently works without any problems or further changes is Ubuntu 14.04.2 LTS 64-bit (the long-term release one). Use anything else at your own risk!

It is also possible to run setup rUNSWift on newer versions of Ubuntu, specifically Ubuntu 16.04. However, please be aware that this is rather untested, and features of offnao (our support tool) may break. If you wish to do so anyway, please first follow all the setup instructions below, then check out Patching Offnao for newer Ubuntu versions.

You can run the OS natively on its own partition, or in a VM, it is recommended to have at least a 30Gb partition and to allocate at least 3GB RAM otherwise bin/build_setup.sh will not work.

On Windows, good VM's are VMWare (which CSE students get for free) and VirtualBox. On Mac OSX, VMWare Fusion is good (also free).

Make sure you defer installing updates during and after your OS setup.

Initial packages

If you are installing a brand new machine, then you should need to install:

• git

Additionally, you may find the following packages useful:

• gitk
• vim
• vim-gnome

Finally, it is worth cleaning up space by removing these packages you might not need:

• LibreOffice

Quick commands:

sudo apt-get install git gitk vim vim-gnome
sudo apt-get purge libreoffice*
sudo apt-get autoremove

Setting up a GitHub account

• Create yourself a GitHub account

• Install your ssh public key into your GitHub account

  Note: If you don't have one you can make one by running: "ssh-keygen -t rsa" (without ") The key will be placed in ~/.ssh/id_rsa.pub

• Set up your git settings to correspond to your GitHub account

  git config --global user.name "Firstname Lastname"

  git config --global user.email "your_email@youremail.com"

While you're here, please remember to add two-factor authentication (2FA) to your GitHub Account if you haven't already.

Good 2FA phone apps include Google Authenticator and Authy.

Setting up the build environment

Before you begin you need to have a few dependencies installed namely: cmake and developer versions of zlib & glib. Try:

# Should have CMake 2.8.12.2, earlier versions tend to have other issues
sudo apt-get install cmake zlib1g-dev libglib2.0-dev

# Extra libraries for 64 bit.
sudo apt-get install libc6-i386 lib32z1-dev libstdc++6:i386 libbz2-1.0:i386 libfreetype6:i386 libglib2.0-0:i386 libsm6:i386 libxrandr2:i386 libfontconfig1:i386

Get our repository and run the build script by copy and pasting the following:

git clone git@github.com:UNSWComputing/rUNSWift-2017-release.git rUNSWift
cd rUNSWift
bin/build_setup.sh

NOTE: You need to be inside the CSE firewall (recommended), or you will need to follow Flashing a Nao (advanced) to get the LINUX_CTC_ZIP file originally from Aldebaran into your rUNSWift/ctc directory.

This will:

• Set up your .bashrc with some robocup environment variables.
• Add your ssh key to the image on the robots.
• Download the cross toolchain (CTC) and generate some Makefiles.
• Do an initial release and debug build.

This can take a long time, maybe half an hour, so now is a good time to go do something else.

Once this is finished, close all open terminals. The build setup creates some environment variables, which need to be loaded before you can run any of the runswift code (such as offnao).

Patching Offnao for newer Ubuntu versions

If you are running Ubuntu 16.04, then it is possible to patch offnao to run on these environments.

You must have first followed the instructions for Manual Setup above.

You will need to download a patch from the runswift server. Quick command - (assuming your working directory is the runswift root directory):

mv /ctc/sysroot_legacy/usr/lib/libGL.so.1 /ctc/sysroot_legacy/usr/lib/libGL.so.1.backup
wget runswift.cse.unsw.edu.au/libGL.so.1 --directory-prefix=/ctc/sysroot_legacy/usr/lib/libGL.so.1

Offnao should now be able to run. If you've questions or trouble getting this to work, please contact Gary.

Post Setup

Pulling the latest code.

If you've used the VM to setup, your code will be behind the latest commit in master. You should rectify this by using git pull. Make sure you've followed the instructions in Setting up a GitHub account first. You will also wish to rebuild - cd to build-release, and type make -jx, where x is the number of threads available on your machine/vm (usually 4).

Editors

You will want to install a text editor to work on the code. An IDE will be useful in this case as the codebase is quite large, and IDE's make it easier to work in these environments.

• CLion is free for university students if you sign up for a free JetBrains account.
• Atom is particularly hackable, e.g. install it then type atom . in any folder 👍
• Sublime is also another great free text editor you can check out.
• Visual Studio Code is a surprisingly great editor. With some small configuration, you can get IntelliSense (autocomplete and more) to work across the entire codebase. It's also easy to build from inside the editor. One useful feature is the ability to jump to class / struct / function definitions.

Final Steps

If you have followed the above steps without any issues then go you should be able to run offnao:

~/runswift/build-release/utils/offnao/offnao

Syncing with the robot

You may find Networking and Passwords useful here.

Make sure the robot you are syncing with has been set up - check Robot Statuses. If the robot has not been set up, see Flashing a Nao. If you are syncing with Tank:

nao_sync <args> tank

or

nao_sync <args> -b build-relwithdebinfo tank

The first is for normal execution, the second is if you want debugging symbols (it will sync from the build-relwithdebinfo directory instead, so make sure you run 'make' there instead of in your build-release directory). You should learn more about the other nao_sync flags with nao_sync --help. Typically, you will run nao_sync -rad tank to sync runswift and remove old files.

Running the code

You can either:

• ssh into the robot with ssh nao@tank.local and run the 'runswift' command, or
• Load runswift by triple tapping the robot's chest or sliding your finger across the touch panels on it's head from front(eyes) to back(fan)

Either way, after doing this you will need to double tap the chest to make it stiffen its body, and then toggle to penalized/playing modes with single taps of the chest.

There is more information on the button press interface and indicator lights at Button Presses For Nao.

Summary

So basically, from now on your build process will be something like:

1. <Make changes to code>
2. cd build-release; make;
3. nao_sync -rad tank
4. Launch the robot through button presses
5. (Depending on what you're doing) Connect to the robot via Offnao and track its progress

Or:

nao_build -j8 && nao_sync -rad odin.local && ssh nao@odin.local

# Then type one of the following commands:
# Start runswift - alternative to button presses
runswift

# Then connect in OffNao

Bonus: Nao command line workflows reference

Legend

• Items with a PC$ prefix should be done on your local machine
• Items with a nao$ prefix should be run at a terminal on the Nao robot.

    # Create a relwithdebinfo build on PC + Nao
    PC$ nao_build_gdb
    PC$ nao_sync_gdb
    PC$ ssh nao@odin.local
    nao$ runswift_gdb

    # Start runswift, force choosing player 5 and run the Striker.py behaviour
    nao$ runswift -n5 -s Striker

    # Restart libagent
    nao$ nao restart

    # Start libagent with debugging output printed to the console
    nao$ nao stop
    nao$ naoqi -d

Optional setup

The image, and Ubuntu by default, is configured to use the Bash shell. Zsh, an alternative shell, may be useful when combined with the oh-my-zsh plugin, which allows the terminal to display branch information about the rUNSWift folder.

Get an offline copy of this wiki on your local machine:

git clone git@github.com:UNSWComputing/rUNSWift.wiki.git

Ready to share code

Great! Please see CONTRIBUTING