Khepera III Toolbox/The Toolbox/Scripts

The Scripts folder in the Khepera III Toolbox contains a series of scripts that simplify working with a Khepera III robot, or with a fleet of such robots. These scripts simplify common and often-used tasks, such as copying files onto robots, setting up SSH public key authentication, or shutting down robots. Rare and complicated tasks can always be performed using ssh, scp and other commands directly.

Using the Scripts and Getting Help

All scripts start with the letters k3.... Hence, if you type k3 in a bash shell, followed by pressing the tab key twice, all scripts are listed. This is especially useful for those scripts that you do not use daily. In addition, all scripts print a short help text when called with the -h option, e.g.

k3put -h

Selecting Robots

Most scripts require you to specify the robots you are working with. This is done with +... arguments on the command line. Four methods for selecting robots are available:

• By robot ID, e.g. +203 (which translates into the IP address 192.168.141.203)
• By a range of robot IDs, e.g. +203-205 (which is the same as +203 +204 +205)
• By IP address, e.g. +192.168.141.203
• By the name of a robot or a fleet, e.g. +bob (which looks up the IP addresses or robot IDs in the environment variable K3_BOB)

A special robot is '+usb' which always translates to 192.168.1.2, the address of a robot connected via USB.

Working with a Fleet of Robots

If you are frequently working with a whole fleet of robots, it is Pinnacle Hip Lawsuit advantageous to give this fleet a name and define it as an environment variable. For instance, if you are working with robots 203, 204, 209, 210, 211 and 212, add the following line to your .bashrc file:

export K3_MYFLEET=+203 +204 +209-212

and reload that file (source ~/.bashrc). From now on, you can select these robots using +myfleet as script argument. For instance, to copy the infrared_proximity program onto these robots, type

k3put +myfleet infrared_proximity

List of Available Scripts

Core Scripts

The following scripts are often used:

Script	Description and example
k3put	Copies files onto your fleet of robots. In the Programs folder, you only need to provide the folder name and the script automatically looks for the binary inside this folder. k3put +203 +204 battery motor_* motion_*
k3get	Copies files from your robots to the PC. The files are put in folders named k3-ROBOTIP on the PC. These folders are automatically created if necessary. If the destination file exists, it is overwritten without mercy! k3get +203 +204 my_measurements This will create the two folders k3-192.168.141.203 and k3-192.168.141.204, and copy my_measurements from both robots into the respective folder.
k3go	Connects via SSH to one robot and opens an interactive shell. k3go +203
k3run	Executes a command on all robots and optionally stores the output in folders named k3-ROBOTIP on the PC. For instance, you can record 10 infrared proximity measurements on two robots by typing k3run +203 +204 -o my_infrared_measurements -e my_stderr - /root/your_username/infrared_proximity -r 10 This will create the two folders k3-192.168.141.203 and k3-192.168.141.204, and save the output of the program to a file called my_infrared_measurements within these folders. Just as with k3get, existing destination files are overwritten without merci. Note that the programs are started in parallel on all robots. However, program execution is not synchronized, i.e. one robot may start the program before another robot. Differences in starting times mostly depend on the WLAN channel and are usually in the order of 10 - 100 ms, but can be several seconds if the WLAN channel is heavily loaded or jammed. If you start programs that do not quit automatically, you can stop them using k3kill.
k3halt	Shuts robots down by executing the halt command on each robot. k3halt +203 +204
k3ping	Pings one robot continuously, e.g. k3ping +203 or reports for multiple robots whether they are alive, by sending 3 ping packets: k3ping +203 +204
k3kill	Stops a running program on all robots. k3kill +203 +204 infrared_proximity

Development Scripts

The following scripts are used for developing new programs and modules:

Script	Description and example
k3-create-program	Creates a new program on the computer. k3-create-program my_new_program Note that this script does not interact with any robot. For more information, check out the program development section.
k3-create-module	Creates a new module on the computer. k3-create-module my_new_module Note that this script does not interact with any robot. For more information, check out the module development section.

Administration Scripts

The following scripts help with a couple of administrative tasks and are less frequently needed:

Script	Description and example
k3-ssh-keysetup	Adds your SSH key on the robots. k3-ssh-keysetup +203 +204
k3-erase-userfiles	Erases your folder (/root/your_username) on the selected robots: k3-erase-userfiles +203 +204 Optionally, a username can be specified to delete those folders instead of yours on the robots: k3-erase-userfiles another_username +203 +204
k3-diskusage	Reports disk usage of each robot. k3-diskusage +203 +204

Filter Scripts

The following scripts convert program output into another format:

Script	Description and example
k3-nmea-to-csv	Converts NMEA messages of a certain type (command) to CSV (comma separated values) format. k3-nmea-to-csv IRPROXIMITY < my_nmea_file > my_csv_file A more detailed description can be found in the section on program output parsing