View source for Getting Started: How to work with kilobots

The following instructions to operate with the kilobots require the firmware 2.0 installed on both the Overhead Controller (see [[OHC Firmware]]) and on the kilobots (see [[Kilobot Firmware]]).

== KiloGUI ==

To operate with the kilobots, we recommend the use of the KiloGUI software.
<br/>
The KiloGUI can be downloaded from GitHub here: https://github.com/acornejo/kilogui
<br/>
A complete documentation about its functioning can be found on the kilobotics website: https://www.kilobotics.com/documentation
<br/>
On Linux, run kilogui with <tt>sudo</tt> privileges.

=== Upload your first control software on a kilobot ===

Try to upload a test control software on kilobots following these steps:
* download the file: [[Media:blank.hex|blank.hex]]
* run kiloGui
* select as Program file the file you just downloaded
* turn on the kilobot by adding the power jumper (see [[Media:Kilobot-power.png|Figure]]), and place it under the IR communication cone of the OHC (see [[Media:Ohc-cone.png|Figure]]).
* click on Bootload button (and the kilobot must switch on the blue LED immediately)
* when the blue LED is on, click on Upload and wait some seconds (the kilobot's LED should blink at high frequency)
* when the kilobot stops blinking, try to run the program on kilobot, by clicking the button Run
* the expected behaviour is the robot keeping blinking in alternate colours red and green. Have fun! :-)

<div style="border:1px solid #8B0000; margin: 5px; background:#FFB6C1;">
:: '''WARNING:'''
:: Do not upload on kilobots files downloaded from this page:
:: https://github.com/SSR-Harvard/kilobotics-labs/tree/master/hex_files
:: They are not compatible with the current firmware 2.0 and will corrupt the kilobot firmware. In case you have done it, the only solution to resurrect the corrupted kilobot is by wire uploading the firmware. If you need to do this, follow the instructions on the page [[Kilobot Firmware]].
</div>

== Write your own control software ==

The API documentation of the firmware 2.0 functions is available here: https://www.kilobotics.com/docs/index.html
<br/>
A good tutorial to learn how to program kilobots can be found here: https://www.kilobotics.com/labs

=== Compile your own control software ===

To compile the control software for the kilobot, use the kilolib that you can download from GitHub here: https://github.com/acornejo/kilolib
<br/>
Needed dependencies are avr-libc, gcc-avr, avrdude:
: on Ubuntu: 
: <code>sudo apt-get install avr-libc gcc-avr avrdude</code>
 
: on Mac OSX:
<pre>
  brew tap larsimmisch/avr 
  brew install avr-libc
  brew install avrdude --with-usb
</pre>

: in case the tap larsimmisch/avr does not work, you can try with this:

<pre>
  brew tap osx-cross/avr
  brew install avr-libc
</pre>

Begin with a test by compiling the <tt>blank.c</tt> file, executing the command:
<pre>
cd <path-to-the-kilolib-dir>
make blank
</pre>
You will find the compiled control software as a <tt>hex</tt> file in the directory <tt>build/</tt>
<br/>
Then, edit the <tt>Makefile</tt> to compile your own code.

Alternatively, you can download and compile another example using the template code available here ([[Media:TemplateForCompilingKilobotCode.zip|Template code]]). <br/>
For Mac users with processor M1, you can use this code ([[Media:TemplateForCompilingKilobotCodeMacM1.zip|Template code for Mac M1]]) which uses Rosetta and a specific version of avr-gcc@12, avr-binutils, and avrdude; in order to make it work with your installation, please edit the file `MakefileTemplate` and use the correct path to your executables.
<br/>
Download the code and execute:
<pre>
cd <path-to-the-template-code-dir>
./compileCode.sh test
</pre>
You will find the compiled control software as a <tt>hex</tt> file in the directory <tt>build/</tt>
<br/>
Then, run the script the <tt>./compileCode.sh</tt> with your filename to compile your own code.