Jump to main content | Jump to Primary Navigation | Jump to Sub Navigation

 
DevBot Core Documentation » Tutorials

Tutorial 3: Creating devices programmatically

Previous tutorial Next tutorial

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 Tutorial 1: First steps, but without the need for an external configuration file.

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

Contents

  1. The lifecycle of a device
  2. Creating a device
  3. Configuring a device programmatically
  4. Bringing it all together

The lifecycle of a device

When a device is created programmatically, using bot_host_create_device(), space is allocated for all the properties of the device as defined in the driver. On creation, devices are attached to a host, and therefore they remain dormant until the host is started with bot_host_start(). Configuration of mandatory properties of the device must take place prior to its host starting up, i.e. before bot_host_start() is called.

Such configuration involves the initialization of the property values using accessor methods defined in property.h. If bot_host_start() is called and at least one mandatory property remains uninitialized a warning is printed and FALSE returned. When bot_host_stop() is called, all devices associated with the specified host are destroyed.

Creating a device

A device using a simple text-output driver is created using bot_host_create_device() from device.h as follows

    bot_host_create_device(host, "DevBot", "simple_driver");

Configuring a device programmatically

Most devices however will require some configuration e.g. a USB serial number. Configuration is achieved by setting the values of the mandatory device properties. There are two mandatory properties for the DevBot device, Countdown and PollPeriod, as well as the optional property, Message. The Countdown property is defined in simple_driver and specifies how many times the device should be polled. The PollPeriod property exists whenever there is a poll_device() method in the driver. In this case the poll_device() merely serves to decrement the countdown property, but it is a useful place to do processing. Both these properties must be set before bot_host_start() is called.

    period = bot_host_register_property(host, "DevBot/PollPeriod");
    bot_property_set_uint(period, 100000);
    countdown = bot_host_register_property(host, "DevBot/Countdown");
    bot_property_set_uint(countdown, 1);

Bringing it all together

Bringing all of the above together yields device_creation.c

/* Simple DevBot application example
 * demonstrating a simple text-output driver.
 * Device created programmatically.
 */
#include <devbot/property.h>
#include <devbot/host.h>
#include <devbot/type.h>

int main(void)
{
    BotProperty *message, *period, *countdown;
    BotHost *host;
    /* create empty BotHost */
    host = bot_host_create();
    /* create new device programmatically */
    bot_host_create_device(host, "DevBot", "simple_driver");
    /* acquire and set mandatory properties */
    period = bot_host_register_property(host, "DevBot/PollPeriod");
    bot_property_set_uint(period, 100000);
    countdown = bot_host_register_property(host, "DevBot/Countdown");
    bot_property_set_uint(countdown, 1);
    /* perform local initialization of the host */
    bot_host_start(host);
    /* acquire message property */
    message = bot_host_register_property(host, "DevBot/Message");
    /* change message property */
    bot_property_set_string(message, "Hello World");
    /* free BotHost data structures */
    bot_host_stop(host);
    /* exit cleanly */
    return 0;
}

Previous tutorial Next tutorial