Creating devices programmatically

This tutorial teaches you how to create devices programmatically i.e. without using an external configuration file. We will produce a program that behaves identically to that described in First steps, but without the need for an external configuration file.

Creating devices programmatically is useful for physically reconfigurable robots, or (more realistically) cases where the configuration file mechanism might be too cumbersome i.e. dealing with 60 range finders positioned regularly around a robot.

Contents

1. Loading a driver
2. Creating a device
3. Registering a device
4. Configuring a device programmatically
5. Bringing it all together

Loading a driver

Creating a device begins with obtaining a driver object. Drivers are represented by the BotDriver data type and manipulated using the functions in driver.h. Mostly, however, one simply needs to load a given driver.

Drivers are loaded using bot_get_driver(). So, for example, to load the example driver

BotDriver *driver = bot_get_driver("example");

Drivers are generally located on LD_LIBRARY_PATH. See driver.h for more details.

Creating a device

Since devices using the example driver require no configuration information we can simply use bot_device_new() as follows

BotDevice *rangefinder = bot_device_new(driver, "rangefinder", NULL, NULL);

Registering a device

Optionally, you may register a device with devbot's core registry. This is useful if you wish to retrieve the device by name, or have it automatically memory-managed. It is left optional since names have to be unique. Devices can be registered using bot_register_device().

bot_register_device(rangefinder);

Configuring a device programmatically

Most devices however will require some configuration e.g. a port number or the like. Configurations are represented by the BotDeviceConfiguration data type and manipulated via the functions in configuration.h. A configuration is a key-value dictionary object where both keys and values are strings (i.e. gchar *)

Let's create a simple BotDeviceConfiguration and add a port value of 8080.

BotDeviceConfiguration *config = bot_configuration_new();
/* Note the quotation marks around 8080! */
bot_configuration_set_value(config, "port", "8080"); 

Keys and value are automatically copied when they're added to a configuration in this way. With a configuration in hand we create a device as usual:

BotDevice *my_thingy = bot_device_create(thingy_driver, "my_thingy", "Description", config);

At this point the configuration object is no longer required and so may be freed with bot_configuration_free().

bot_configuration_free(config);

Bringing it all together

/*******************************************************************************
 * Creating devices programmatically
 *
 * This example program illustrates how to use devbot without a device
 * configuration file.
 * 
 *******************************************************************************/

/* Include the main bot.h and speech interface definition as before */
#include <devbot/bot.h>
#include <devbot/distance.h>

/* This time however we'll need to manipulate driver objects too */
#include <devbot/driver.h>

int main(int argc, char **argv)
{
  /* 1. Initialize the devbot library */
  bot_initialize();
  
  /* 2. Create a driver object
   * 
   * This has the side effect of dynamically loading, initializing and
   * registering the driver */
  BotDriver *driver = bot_get_driver("example");

  /* 3. Check that this process was successful
   * 
   * Again, this is not necessary, but is good practice. */
  if (!driver)
  {
    exit(1);
  }

  /* 4. Now we'll create a distance measuring device using this driver */
  BotDevice *rangefinder = bot_device_new(driver, "rangefinder", NULL, NULL);
  
  /* 5. Check it was created successfully */
  if (!(rangefinder && bot_device_get_interface(rangefinder, BotDistanceInterface)))
  {
    exit(1);
  }

  /* 6. Retrieve and print the current distance */
  g_message("Distance was: %lf", bot_distance_get_metre(rangefinder));

  /* 7. Since we're finished with it, we'll dispose of it */
  bot_device_free(rangefinder);

  /* 8. Shutdown the libarary */
  bot_shutdown();
}

---