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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]Core Scripts
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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 |