# Khepera III Toolbox/Introduction

The Khepera III robot runs an embedded Linux (kernel 2.6) with all of the most common Linux tools, except for program compilation. Hence, programs have to be cross-compiled on another computer with a arm-linux toolchain, and can then be copied using SCP and launched over an SSH connection. This is in principle quite straightforward for a Linux adept, but can be quite cumbersome when starting from scratch.
This is where the Khepera III toolbox comes into play. The toolbox can be understood as a Swiss Army Knife for the Khepera III robot, offering three different types of tools:
* Scripts to interact with the robot(s): A series of scripts are available to copy files on your robots, remotely execute programs, and do a number of administrative things. These scripts can deal with many robots in parallel, e.g. to copy a file onto a whole fleet of robots.
* Programs for the Khepera III robot: A number of small programs are available to play with the sensors and actuators of the robot.
* Modules with standard functionality: A couple of modules provide basic functionality that you can easily integrate in your own programs that you write for the Khepera III robot. Besides functions to read the sensors and configure actuators, there are also modules to parse command line arguments, simple odometry tracking, and so on.
The remainder of this chapter shows in a tutorial-like style how to do a couple of fancy things with the robot, using the scripts and the programs. The modules are discussed in a later chapter.

## Preparing the Computer and the Robot

We assume that you installed the Khepera III Toolbox as explained in Download and Installation and that you are using a bash shell on a recent Linux system.
Switch on your Khepera III robot and connect it to your computer. For the remainder of this introduction, we will assume that your robot is connected with a USB cable. If you are using a WLAN connection, simply replace the "+usb" with "+ROBOTID" (where ROBOTID is the number of your robot).
To check if everything is all right, type
which will execute ping 192.168.1.2 for you.
Both your computer and the robot should be ready now - time to play with the robot!

## Remote Control with a Keyboard

Type
to copy three of the motor programs to your robot. (Note that you will need to type the root password of the robot 4 times. This password is "rootme" by default.) As you can see in the terminal, this just launches scp commands.
Now type
and type the root password again to log onto the robot. If you now type ls (on the robot), you will notice that a directory with your username has been created. This is a convenient way to avoid overwriting each others files if your fellows are using the same robot as well. Hence, cd into this directory and type:
The first program will initialize the motors (e.g. set PID values) and then quit. The second program keeps running until you press Ctrl-C, and allows you to steer the robot with the keys W (increase speed), A (turn left), S (stop), D (turn right) and X (decrease speed) on the keyboard.
Note that when you quit this program with Ctrl-C, the motors will keep the last speed they were told. This is a general rule for all programs of this toolbox, and should be seen as a feature - not a bug. A program which comes in handy sometimes is "motor_stop", which immediately stops the motors.
Once you have played enough with the robot, you can log out by typing
on the command line. This brings you back on the computer, to the place where you were before the k3go command.

## Fun with the Infrared Sensors

Two programs are available to query the infrared sensors: infrared_ambient and infrared_proximity. While the former simply reads all infrared receivers, the latter takes two consecutive measurements (once with the IR LED off and once with the IR LED on) with each sensor to estimate its distance to an obstacle.
Again, we first need to copy the necessary programs onto the robot. Assuming that you are still in the Programs directory, type
Then, log on to the robot (k3go +usb) and cd to your directory.
Get an ambient IR measurement by typing
This will give you something like:
The first two values denote the sample number (starting at 0) and the current timestamp of the main microcontroller. All other values are in the range 0 - 4096 and correspond to one sensor on the robot. The sensors are numbered clockwise (when looking from the top) from 0 (back left sensor) to 8 (back sensor). Sensors 9 and 10 are the right and left floor sensors, respectively. On a sunny day, you can cover one sensor with a finger while taking another measurement, and you should see a clear difference between the values. Similar experiments can be made in proximity mode (./infrared_proximity).
Instead of launching the command several times, you can tell the program to take several (here: 10) measurements in a row
or to take measurements until pressing Ctrl-C

### Output Format

At this point, you may be wondering about the output format, notably the $IRAMBIENT the beginning of all lines. This is NMEA 0183, a very simple text-based communication format which has become widespread through GPS devices (which almost always use this format). More information about this format is written in the chapter Parsing Program Output.

## Measuring Distances with the Ultrasound Sensors

The Khepera III robot is equipped with 5 ultrasound sensors which can be used to detect obstacles. When switched on, these sensors send out an ultrasound pulse and record its echo. Since the propagation of acoustic waves in the air is almost constant, this technique can be used to measure distances to objects in the environment. Note that the story is slightly more complicated, though. What you record when sending out a pulse is a combination of a whole series of echos, reflected by various objects in the environment. Fortunately, the robot processes the signal for you and provides you the most prominent echos in the received signal.
Type
to copy these two programs onto your robot. Now log on to the robot (k3go +usb) and cd to your directory.
Point your robot towards a wall and type
You will get something like this
Each line corresponds to one received echo and contains its amplitude as well as the estimated object distance. In our example, we got a very strong echo from an object at a distance of 0.98 m, and two less strong echos from objects at 0.45 m and 1.22 m distance. Note that the accuracy is in the order of a few centimeters, and you may get slightly different values each time.
By default, only the front sensor is enabled. To activate the left and the right sensor as well, type
This program will configures the robot accordingly reports the active sensors. Now, you can also take measurements with the sensors on the left and on the right:

## Getting Help

To get help about one of the standard programs, simply invoke the program with the -h option:
Reading this help and a little bit of imagination should make the use of all standard programs straightforward.

## More Tutorials and Hands-On Exercises

For more tutorials, have a look at the Examples section. These examples are written in such a way that you can reproduce them with your own Khepera III robot, and gradually learn more about it.