Basic Usage

Creating a simple robot

For this first example, we’ll use the built-in Kilosim::Kilobot robot. Place this in a src folder within your project’s root directory. If you want to use a different robot model (or make your own), see the Advanced Usage section.

To create the code that runs on your robot, you need to create a class that inherits from Kilosim::Kilobot, as shown below. This needs to implement the following functions (based on the Kilobot API):

• Kilosim::Kilobot::setup(): Runs once at the beginning of the simulation. (Note: This is run when the robot is initialized, not when it’s placed in the World, so you don’t yet have access to World-related values like position.)

• Kilosim::Kilobot::update(): Runs once per simulation step.

• Kilosim::Kilobot::message_rx(): Runs when the robot receiver a message from another robot.

• Kilosim::Kilobot::message_tx(): Creates the message that the robot will transmit.

• Kilosim::Kilobot::message_tx_success(): Runs when the robot successfully transmits a message.

For more details of the Kilobot API, see the documentation for the Kilosim::Kilobot class and the Kilobot API.

Below is an example of the minimum requirements for your robot class, which you can use as a template for your own robot. You can also download this directory: minimal_kilobot.py

/*
    This is a barebones example implementation of a Kilobot class
*/

#include <kilosim/Kilobot.h>

#include <iostream>

namespace Kilosim
{
class MyKilobot : public Kilobot
{
public:
  // Declare any attributes that you want to be accessible to aggregator
  // functions as public.
  int16_t light_intensity = -1;

private:
  // Declare any other (internal) persistent attributes here.

  // REQUIRED KILOBOT FUNCTIONS

  void setup()
  {
    // This code will be run once when you call `robot_init(x, y, theta)`
    // Note: This should only be done AFTER the Robot has been added to a World
  }

  void loop()
  {
    // This code is run once per kilo_tick.
  }

  // OPTIONAL KILOBOT FUNCTIONS

  void message_rx(message_t *message, distance_measurement_t *distance_measurement){
      // This is called when a message is received
      // On real robots, this is called as an interrupt, so processing here
      // (outside the loop) should be minimized
      // Implementing this overrides the default function, which does nothing
  };

  message_t *message_tx()
  {
    // This produces the message to send.
    // Implementing this overrides the default function, which returns NULL
    // (No message transmitted)
  }

  void message_tx_success()
  {
    // This is called when a message is successfully transmitted
    // Implementing this overrides the default function, which does nothing
  }
};
} // namespace Kilosim

First Simulation

Setting up CMake

Using the Viewer

• Add it to the main function

• Call it once per step (or less frequently)

Configuration and Parameters

Configuration files are defined as JSON files and can be loaded with a ConfigParser. The contents of flat JSON files can be automatically saved with your data using the Logger. (Support for saving JSON objects and arrays to HDF5 may be added in the future if someone needs/wants it.)

There are no fixed requirements for the contents of the configuration files; it’s an un-opinionated convenience tool for importing and using whatever (atomic) parameters you want.

Logging

• Create a Logger

• Creating aggregator functions

• Call every couple steps/seconds