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

Initializing the library

Programs using DevBot should always begin by including host.h, then initializing a BotHost variable with bot_host_create(). This creates an empty BotHost which is ready to have BotDevice and BotProperty instances associated with it. The command bot_host_start() performs local startup of a BotHost. Once you've finished using DevBot you should call bot_host_stop() to free-up internal data structures. So the simplest program you can write using devbot looks like this:

#include <devbot/host.h>
int main(void)
{
    BotHost *host;
    /* create empty BotHost */
    host = bot_host_create();
    /* perform local initialization of the host */
    bot_host_start(host);
    /* free BotHost data structures */
    bot_host_stop(host);
    /* exit cleanly */
    return 0;
}

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 devbot` basic.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.xml)

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <host id="Default">
        <device name="DevBot" driver="simple_driver">
            <property name="Countdown">10</property>
            <property name="PollPeriod">100000</property>
        </device>
    </host>
</configuration>

This example defines a single device called DevBot using the simple_driver has a polling period of 100,000 microseconds and a countdown property with value 10. Devbot can be initialized with a configuration file using the bot_configure_file() command, defined in configuration.h. The first argument of bot_configure_file() specifies the BotHost to configure, the second argument indicates the configuration file to use, and the third argument points to the relevant section of the configuration file. After configuration, the command bot_host_start() performs local startup of a BotHost.

#include <devbot/host.h>

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

Obtaining the property

For this text-output example we need a pointer to the Message property of the DevBot device.

    BotProperty *message;
    message = bot_host_register_property(host, "DevBot/Message");

Modifying the property

To change the current value of the Message property we include property.h and then simply call

    bot_property_set_string(message, "Hello World");

Bringing it all together

Bringing all of the above together yields basic.c

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

int main(void)
{
    BotProperty *message;
    BotHost *host;
    /* create empty BotHost */
    host = bot_host_create();
    /* load configuration file */
    bot_configure_file(host, "basic.xml", "Default");
    /* 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;
}

Back to main tutorial page

Next tutorial