First steps

This tutorial concerns reading a configuration file and accessing devices through the hardware abstraction layer

Contents

1. Initializing the library
2. Compiling the example
3. The configuration file
4. Obtaining the device
5. Using the device
6. Bringing it all together

Initializing the library

Programs using devbot should always begin by including bot.h and calling bot_initialize() or bot_initialize_from_file(). Once you've finished using libbot you should call bot_shutdown() to free-up internal data structures. So the simplest program you can write using devbot looks like this:

#include <devbot/core/bot.h>

void main(int argc, char **argv)
{
    bot_initialize();
    /* Do some stuff */
    bot_shutdown();
}

Compiling the example

On a correctly configured system, building the above program should be a matter of issuing the following command:

gcc -o basic `pkg-config --cflags --libs glib-2.0 devbot` tutorial.c

The configuration file

Devbot includes a mechanism allowing device names and configuration to be defined at runtime. Here is an example of a simple configuration file (basic.config)

[rangefinder]
Driver = example

This example defines a single device called voice using the flite speech synthesiser driver. Devbot can be initialized with a configuration file using the bot_initialize_from_file command e.g.

#include <devbot/core/bot.h>

void main(int argc, char **argv)
{
    bot_initialize_from_file("basic.config");
    /* Do some stuff */
    bot_shutdown();
}

Initializing from a file automatically locates and loads any referenced drivers before creating and configuring each device.

Obtaining the device

In our case, just one device was specified. It can be obtained by name using the bot_get_device() function i.e.

BotDevice *rangefinder = bot_get_device("rangefinder");

Using the device

Since rangefinder uses the example device driver we know that it implements the BotDistanceInterface. Thus we can use any of the functions specified in distance.h. To retrive the current distance measurement in metres we simply call

bot_distance_get_metre(rangefinder);

Bringing it all together

Bring all of the above together yields basic.c

/*******************************************************************************
 * First Steps
 *
 * This is a program to demonstrate the basic use of the DevBot
 * APIs. It covers initializing the library, configuring a device from
 * a text file, retrieving that device by name and then using it to do
 * something.
 *
 * This represents the standard use case.
 * 
 *******************************************************************************/

/* Include the main devbot header, all devbot-based applications will
 * do this */
#include <devbot/bot.h>

/* Include the headers for any interfaces we're going to use, in this
 * case we're just using the distance sensor interface
 * BotDistanceInterface */
#include <devbot/distance.h>

int main(int argc, char **argv)
{
  /* 1. Initialize the devbot library specifying a device configuration file */
  bot_initialize_from_file("basic.config");
  
  /* 2. Retrieve a device by name */
  BotDevice *rangefinder = bot_get_device("rangefinder");
  
  /* 3. Check we've got the device and that it supports the distance
   * interface.  
   *
   * It is not *necessary* to do this, but should be considered good
   * defensive programming practice */
  if (!(rangefinder && bot_device_get_interface(rangefinder, BotDistanceInterface)))
  {
    exit(1);
  }

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

  /* 5. Shutdown the libarary
   * 
   * This will free internal data structures, unload drivers etc.
   * It is not *necessary* to do this, but it is good practice */
  bot_shutdown();
}

---