Khepera III Toolbox/The Toolbox/Programs

The Programs folder contains a series of useful programs and algorithms that run on the Khepera III robot, and interact with its sensors and actuators (motors). These programs are also useful templates to implement your own algorithms. In this chapter, we briefly explain how to use these programs.

Program List

Infrared sensors (including the two infrared floor sensors):

• infrared_ambient: Measures the ambient infrared light with all infrared sensors.
• infrared_proximity: Measures the proximity to obstacles with all infrared sensors.

Motors:

• motor_initialize: Initializes both motors. This program must be launched after switching on the robot.
• motor_setspeed: Sets the motor speed.
• motor_stop: Stops both motors immediately.
• motor_setposition: Sets the current position of the motor encoders.
• motor_gotoposition: Drives the motor to a specific motor encoder position.
• motor_getposition: Returns the current position of the motor encoders.
• motor_configuration: Prints the complete configuration (registers) of both motors.
• motor_setspeedprofile: Sets the trapezoidal speed profile.

Ultrasound:

• ultrasound_enable: Enables or disables the ultrasound sensors.
• ultrasound: Measures the proximity to obstacles with the ultrasound sensors.

Battery:

• battery: Returns the current state of the battery.

General:

• firmware_version: Returns the firmware version of the dsPIC and the motor PICs.
• test_math: Tests a couple of mathematical functions. This program serves more as a template rather than a useful program.
• tcp_server: Demonstrates how to write a program which accepts a TCP connection.
• i2c: General I2C utility.
• i2c_readstream*: Reads a data stream from an I2C device.

Motion:

• motion_braitenberg: Implements object following, obstacle avoidance and wall following using the Braitenberg algorithm.
• motion_arrowkeys: Allows to drive the robot around using the keyboard.
• motion_followline: Makes the robot follow a line on the ground.
• motion_forwardbackward: Makes the robot continuously move forward and backward.
• motion_random: Drives the robot randomly around.
• motion_spiral: Makes the robot move along a spiral.

Odometry:

• odometry_track: Tracks the position of the robot based on differential-drive odometry using the encoder values.
• odometry_goto: Drives the robot to a given target position, while keeping track of its position using odometry.

Programs marked with an asterisk (*) are currently incomplete and need some reworking to be done.

Launching a Program

Each program is stored - with its source code, a Makefile, a compiled binary and possibly additional material - in a subfolder of Programs. The binaries are compiled for the Korebot platform (ARM processor running a Linux kernel 2.4) and therefore only run on the Korebot.

To use a program, copy it onto your robot first:

cd Programs
k3put +usb infrared_proximity

(If your robot is connected via WLAN, replace the +usb by +RobotID.) Then, log on to your robot by typing

k3go +usb

and launch the program there

cd your_username
./infrared_proximity

The program will write its output directly in the terminal window.

Getting Help

Each program prints a little help text when launched with the -h option, e.g.

./infrared_proximity -h

Redirecting the Output of a Program to a File

In some cases, you may want to write the output of a program (e.g. infrared proximity measures) to a file instead of displaying it on the screen. The standard Linux tools offer several ways to achieve that:

To write the output to a file on the robot, simply redirect the output to a file when launching the program:

./infrared_proximity > my_infrared_proximity_measures

Note that there is only about 1 MB of space available on the robot.

To write the output to a file on your computer, launch your program via SSH and redirect the output to a file. For those not so familiar with SSH, this may get a bit tricky. But fortunately, there is a Khepera III script which does all that for you automatically:

k3run +usb -o my_output_file /root/your_username/infrared_proximity -r

If your robot is connected via WLAN, replace the +usb by +RobotID. This transfers the output of the program over the network connection and stores it in the file my_output_file in the folder k3-192.168.1.2 on the computer. This is actually faster than writing the output to a file on the robot (even if this sounds counter-intuitive), because WLAN transmission is usually faster than writing to the flash memory on the robot.

Running Multiple Programs at the Same Time

You can run several programs on the robot at the same time. This can make sense, for instance, if you want to steer your robot with the keyboard (motion_arrowkeys) and log infrared sensor measurements at the same time (infrared_ambient, infrared_proximity), or track the path of the robot (odometry_track). This is also useful for monitoring the battery level with a program running in the background.

To achieve that, you can log in several times on the same robot (k3go), run one program in the background (e.g. ./infrared_ambient > my_measures &), or launch some programs from the computer (k3run).

There are a few things to keep in mind, however:

• It does not make sense to run two programs which both set motor speeds. Each time one programs sets the speed, the old speed is overwritten, resulting in quite unpredictable behavior.
• One program may slow down the other program. The CPU is a shared and limited resource (use top to check CPU usage), but even more so is the I2C bus which is used to communicate with the sensors and actuators of the robot. You should therefore avoid reading the same sensor value with several programs in parallel.

Important note: If you are running programs based on the libkorebot library from K-Team, you should never run any other program accessing the sensors or actuators in parallel, as this may cause such programs to obtain wrong sensor values or crash.