Documentation


This page contains the basic information required to get started with the Kilogrid system.
The Kilogrid system is composed of three parts:

  • a set of Kilogrid modules
  • a dispatcher
  • the KiloGUI application

Hardware Specifications

Modules

The Kilogrid module consists of a PCB board enclosed within laser-cut structural components. Modules can be programmed by the user in the same fashion of Kilobot robots. Each module has a size of 10x10 cm and is divided into four 5x5 cm cells. Every cell can communicate with Kilobots through IR messages and provide visual feedback through colored LEDs. Modules can be programmed simultaneously through the CAN network (using kiloGUI) or independently through ICSP connection (required for flashing the firmware or EEPROM memory). Module firmware is written in C language, using an extended version of the kilolib library for the Kilobot robot. Each module contains an unique 10-bit identifier stored in its EEPROM memory, containing information about its position in the grid of modules.

Dispatcher

The dispatcher interfaces a grid of connected modules with a remote workstation, and consists of a single PCB board protected with two layers of laser-cut plexiglass (14x13 cm). It substitutes and replaces the original Kilobot overhead controller in all of its functionalities, such as upload a Kilobot program on the robots or send Kilobots into sleep state. The dispatcher provides a bidirectional communication channel between Kilobots and KiloGUI, allowing for the log of data during experiments.


The MCU of the dispatcher is connected to the grid of modules through CAN interface and to the KiloGUI application via USB interface. It transmits commands issued through KiloGUI to the Kilogrid modules and forwards data received from the modules to KiloGUI. The CAN interface has a network speed of 250Kbps, which decouples the CAN network into 4 buses, each allowing up to 112 connected modules. CAN messages consist of 64 bits available to the user and 51 bits for addressing, synchronization and acknowledgment of the message. Communication over the CAN network can be peer-to-peer, multi-cast (both by row and column), or broadcast. Messages from modules are stored into a buffer and periodically pooled from the dispatcher, which forwards the data to the KiloGUI application.

KiloGUI software

The KiloGUI software is an extension of the original KiloGUI application for the Kilobot robot. It allows the user to load and execute controllers both for Kilogrid modules and Kilobots. For a detailed explaination of Kilobot commands, please refer to the Kilobot documentation.


Functionalities Description
Configuration Select a configuration file. Data contained in configuration files will be loaded into the modules when clicking the Setup button. See the Downloads section for examples of configuration files.
Program Select the desired Kilogrid module program. Takes a .hex file as input, same as the Kilobot robot. See the Downloads section for examples of module controllers.
Bootload Prepares the modules for the upload of a program. Module LEDs will light up blue. The upload command can be issued right after.
Upload Uploads the program to the modules. Module LEDs will blink blue and green. When the LEDs animation ends, the program has been successfully uploaded.
Setup Runs the setup function written in the module controller. Data from the configuration file will be loaded into the module. Handling of the configuration file must be specified inside the setup function.
Run (Stop) Issues a Run command to the Kilobots and starts the execution of the module program. Once the program has started, the Run button turns into Stop. Issuing a Stop command terminates the execution of the module program and the collection of data messages.
Experiment log Data messages forwarded to the KiloGUI application will appear here during the execution of a program. Data is additionaly stored on a local data file on the workstation.
Clear Clears the data inside the Experiment log.

Setup

Initial module flash


Building the Kilogrid

Structural components of the Kilogrid: a) support islands (corner/side); b) IR barriers (female side/male and female middle); c) internal IR barriers (male/female); d) light diffuser; e) PCB supports (corner/side/middle)

Testing the modules

You can test the correct functioning of Kilogrid modules using the test software provided in the Download section. The provided controllers test the LEDs, IR transmitte rs and IR receivers of all cells inside the module. Modules to be tested need to be connected to the kiloGUI application through the dispatcher. You will need a kilobot robot to test the functioning of IR functions.


Writing a module controller

We will briefly describe how to write a module controller, by analyzing the wall avoidance controller. The source code of the module program, along with the kilobot program and required configuration files are provided in the Download section.

cell_num_t cell_id[4] = {C00, C01, C02, C03};
IR_message_t IR_message_tx[4];
IR_message_t IR_msg_rx;

Declaration of cell_id, used as index to address cells inside the module, and of variables for IR transmission and reception.

volatile uint8_t wall_gradient[4] = {0, 0, 0, 0};

Declaration of array wall_gradient, which will contain the gradient values used for wall avoidance for each cell in the module.

void IR_rx(IR_message_t *m, cell_num_t c, distance_measurement_t *d, uint8_t CRC_error) {
	if(!CRC_error && m->type == TRACKING){
		CAN_message_t* msg = next_CAN_message();
		if(msg != NULL) {
			serialize_tracking_message(msg, c, m->data);
		}
	}
}

Function activated whenever a cell receives an IR message. In this example, if the message is of type TRACKING, it is forwarded to the kiloGUI apllication through the CAN network.

void setup()
{
    obstacle_gradient[0] = configuration[0];
    obstacle_gradient[1] = configuration[1];
    obstacle_gradient[2] = configuration[2];
    obstacle_gradient[3] = configuration[3];
}

Function activated when the Setup button is pressend in kiloGUI. In this example, we set the appropriate gradient value for each cells, read from the configuration file.

void loop(){
	for(int i = 0; i < 4; ++i){
		IR_message_tx[i].type = MESSAGE_GRADIENT; 
		IR_message_tx[i].data[0] = wall_gradient[i];
		set_IR_message(&IR_message_tx[i], i);	
		switch(wall_gradient[i]){
	 		case 2:
	 		set_LED(cell_id[i], RED, MEDIUM);
	 		break;
	 		case 1:
	 		set_LED(cell_id[i], RED, LOW);
	 		break;
	 		default:
	 		set_LED(cell_id[i], LED_OFF, LOW);
	 		break;
		}
	}       
}

Loop function. Code inserted here will be repeated for the entire experiment duration. In this case, we set the IR tx data for each cell (type and gradient value). Inside the switch, we light up the LEDs of each cell depending on its gradient value.

int main() {
    module_init(); 
    module_IR_message_rx = IR_rx;
    module_start(setup, loop);
    return 0;
}

Standard main funtion for modules. First we initialize the module utilities, then we set our previously defined function IR_rx as callback when a message is received. Finally, the loop function is launched from module_start.