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.

• single MCU, ATmega328P with 32KB of memory and running at 8 MHz (same as Kilobot).
• 4 independently controlled cells.
• 4 IR receivers and transmitters (one per cell).
• 8 RGB LEDs (2 per cell).
• CAN controller and CAN transceiver.
• Onboard voltage regulator (supplies the module with 5 V).
• ICSP connection.

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.

• ATmega328P MCU with 32KB of memory and running at 8 MHz (same as Kilobot and Kilogrid module).
• 2 CAN repeaters.
• USB connection.
• Serial connection.

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.

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)

The 5 structural components are positioned in the following order:

1. support islands (made from wood panels)
2. PCB support (made from wood panels, screwed to support islands)
3. IR barriers (made of black plexiglass)
4. a grid of connected modules (PCB boards)
5. internal IR barriers (made of black plexiglass)
6. Light diffuser (made of white translucent plexiglass)

The assembled Kilogrid is then placed under a single transparent plexiglass surface, on which the Kilobots move.

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.

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.