DevBot can attach one or more callbacks to properties, so if the property value is updated, any number of user functions are called. Additional flexibility is provided to allow updates to be dropped (and not call the callback) if the previous callback invocation did not yet complete.

This allows complex systems to be built where one event can have a knock-on effect or emit other events. Frequent events can also be accumulated to produce one more significant (but less frequent) event. Such techniques can be used to implement complex virtual sensors.

Callbacks are executed concurrently in response to property updates by the Dispatcher .

See also:: Callback API documentation

Devices

A device is an instance of a Driver, which has its own copy of private state information, and a unique name. The relationship of device-to-driver is therefore one-to-many. Devices are represented by the opaque BotDevice data type and can be created by the bot_host_create_device() function, or by configuration file specification. When devices are instantiated, the may contribute properties to a host's property table.

See also:: Device API documentation

Dispatcher

The dispatcher is responsible for running application-provided Callback in repsonse to property updates. These callbacks are executed by threads drawn from a dispatcher pool and may run concurrently.

Like the Scheduler a single dispatcher instance services all hosts within an application process.

Driver

A driver provides support for a specific type of hardware connected in a specific way. Drivers are loaded "on-demand" in response to calls to bot_host_create_device() . The configuration parser may also (by proxy) invoke driver loading. All drivers must be in the system library search path (LD_LIBRARY_PATH on Linux). Drivers are represented by the opaque BotDriver data type.

Although Edinburgh Robotics provides a hardware support service, there is a public API for driver authors. See Drivers 1: A new device driver for more information.

See also:: API for driver authors

External type

An external type is a PropertyType that is defined outside the DevBot Core library and that must be explicitly loaded before use.

See also:: Tutorial 6: External Types

Host

Globally, a host is a container for properties, which can be transparently accessed from any other host on the same network. Locally, a host has devices that may be built programmatically or from configuration XML. They are represented by the opaque BotHost data type.

A host has two unique identifiers -- an IP and a port -- which it uses to bind to the machine it is initialized on. In this respect, a single process may provide one or more hosts simultaneously, each with their own devices and access properties from any other host provided by any other process. This allows a process to initialize hosts on many network interfaces simultaneously.

Naming Convention

Functions are prefixed by "bot_". Types are prefixed by "Bot". Global variables and constants are prefixed by "BOT_".

Property

DevBot uses on Properties to represent all data in a system. Properties generally take on a single value, but an array of the same type is considered acceptable (for example strings, or vectors). In this respect, Properties are similar to database fields or the Linux sysfs filesystem (which subscribes to a similar "one value per file" philosophy).

Properties are fully thread safe, network transparent and each has a name, a type, and storage space for the values. They are represented by the opaque BotProperty data type.

Thread safety

All DevBot API functions are thread-safe. In particular, property access is guarded by a (per-property) lock. This also means they are totally sequentially consistent within a local host. That is, callbacks listening to updates on a property will see them in exactly the same order as they were written, regardless of threading. Furthermore, the DevBot API exposes these property locks (see bot_property_lock()) to support transactional use cases.

Timestamps

Properties are automatically timestamped when their value is altered. This time stamp can be retrived with bot_property_get_timestamp(). This has a wide variety of useful applications, however timestamps are always based on the local time and thus cannot be meaningfully compared between remote hosts without some additional synchronization mechanism.

Network transparency and reflection

All properties are fully and automatically network transparent. Hosts each store a "table" of properties they have cached, which initially contains only local properties. Properties can, however, be "registered" from remote hosts. The property description is then marshalled and sent to the requester using a transparent HTTP/XML protocol, and added to the requester's property table.

Requesting a remote property involves passing a fully qualified URL to the bot_host_query_property(). Strictly speaking, such URLs have the form "ip:port/property_name", but since most properties are provided by device drivers, "ip:port/device_name/property_name" is typical.

Remote properties are cached locally on all hosts that are interested in them. This enables higher performance local manipulation of a property, but due to vagaries in network latency and the risk that updates may be lost completely, DevBot does not provide a globally consistent total ordering for remote property updates. Close attention must be given to system design if DevBot is to be run over unreliable network channels.

Access control

Typically, properties can be read or written. However, some properties may have additional restrictions preventing one or both of these operations. Drivers may use 'private' variants of the set/get functions to override such access controls.

Scheduler

Writing device drivers involves writing a poll_device() method which does one unit of work. For most applications, this defines the resolution of the value, and should be run as infrequently as possible.

DevBot has its own scheduler that allows for fine-grained control over the number of consecutively running threads, enforces driver deadlines, and provides statistics about driver poll_device() routines.

One key advantage of this is that writing device drivers allows properties on devices to be kept up to date, automatically. So a driver can explicitly set a property in its poll_device() function, and the update is visible to other readers of that property. See Dispatcher for a means of handling updates to a property. This topic is also discussed in more depth (with examples) in the Poll Function section of the driver tutorial.

Only one scheduler is created per instance of the core DevBot library i.e. all hosts running within an application utilise the same scheduler.

Type

Properties are strongly and statically typed in that every property has a type which does not change over its lifetime. Although DevBot provides many types as standard (including all basic C types) it is possible to create custom types for specific applications.

See also:: API for value types