Gadgeteer serves to hide input device hardware from programmers so that immersive software may be written that can take advantage of a wide variety of devices. This goal arises from previous experience with software toolkits that tied immersive applications to specific devices, thereby limiting the portability of the applications between immersive hardware configurations. With Gadgeteer, applications can be written that migrate transparently between different hardware configurations with no required knowledge on the part of the application author relating to vendors, models, drivers, etc.

Gadgeteer categorizes input devices based on abstract input types. The categories are the following:

Each of these is described in more detail below in the section called “Device Types”.

In this categorization, devices from different vendors may return data that maps to the same abstract form. A single piece of hardware may even map to multiple input types, and more device types can be added as new hardware becomes available. Application authors write their code in terms of abstract input types, so as long as a device is available that provides the needed input, the application can function.

In keeping with the general goals of Gadgeteer, device driver authors should strive to achieve certain goals for each device driver they write. In no particular order, we feel that the most important goals are the following:

For the most part, these goals are no different than those of any other software project. Nonetheless, we will explain why each is important in the following subsections.

Before discussing features of VPR useful to device driver authors, we must first understand how I/O is handled in VPR. All I/O classes (file handles, serial ports, and sockets) share the base class vpr::BlockIO. Reads and writes are performed using blocks of memory (buffers). This design provides an API that more closely resembles that of the underlying operating system (with methods called read() and write()), but it is in contrast to stream-oriented I/O that is usually seen in C++. Streams could be written on top of the buffered I/O classes, but thus far, the need has not arisen. With this in mind, the design provides an API that is immediately familiar to programmers used to POSIX-based interfaces, but the API may seem clumsy to C++ programmers who are accustomed to using std::ostream and friends.

Most input devices used for virtual reality systems today make use of a computer's serial port for data communication. For that reason, it is important that device driver authors have at least a basic understanding of the concepts behind the VPR serial port abstraction. In our experience, serial port programming is not much different than other I/O programming. Implementing the communication protocol used by a given device tends to be the hard part, and that will likely be the case regardless of the underlying hardware.

The VPR serial port abstraction is based on the concepts implemented by the standard termios serial interface used by most modern UNIX-based operating systems [Ste92]. As such, the API allows enabling and disabling of a subset of the serial device features that can be manipulated using termios directly. To provide cross-platform semantics, however, some termios features are not included because there is no corresponding capability with Win32 overlapped I/O. Furthermore, any termios settings that relate specifically to modems are not included in the VPR serial port abstraction.

The socket abstraction follows the concepts set forth by the BSD sockets API, which was also the model for the Winsock API used on Windows. In VPR, two types of sockets may be instantiated: stream-oriented (TCP, vpr::SocketStream) and datagram (UDP, vpr::SocketDatagram). The helper class vpr::InetAddr makes use of Internet Protocol (v4) addresses easier. Built on top of vpr::SocketStream are two classes that make writing client/server code easier: vpr::SocketConnector and vpr::SocketAcceptor. The vpr::System interface provides cross-platform data conversion functions to deal with endian issues.

The utility of various socket classes will vary depending on the needs of a given driver protocol. It is usually safe to assume that the driver will connect to a server of some sort that will send out device samples. Unpacking information from the samples may or may not be necessary, depending on the protocol. Such concerns are left entirely to the driver authors.

All device drivers written for Gadgeteer will process samples in a thread separate from the Input Manager. We have chosen this design to avoid the complications that often arise from using non-blocking I/O and to allow the drivers to act more as independent entities. Thus, it will be important to understand how to use the VPR thread interface.

First and foremost, developers must always remember that Gadgeteer uses a shared-memory model for all threads, regardless of the underlying platform-specific thread interface. This follows the lightweight thread model set forth by the POSIX threads (pthreads) standard. With a shared-memory model, all threads have access the same memory, and thus it will almost certainly be necessary to control access to shared variables. In most cases, the class vpr::Mutex will provide sufficient control over multi-threaded data access.

Device driver authors will probably not have to do much with shared data access control because the driver will operate almost entirely in the sample loop thread. Any other method invocations (starting the driver, stopping it, configuring it, etc.) will happen in the Input Manager thread, and common memory accesses have pre-defined helper methods to simplify the work of driver authors. These details will be explained further in later chapters.

The various VPR abstraction interfaces are documented extensively, and readers are encouraged to review the VPR Programmer Reference (refer to the VPR website for more information).

The VPR class names follow a standard convention, and understanding this can be helpful in navigating the API documentation. Classes that wrap platform-specific interfaces are named as follows: vpr::<Type><Platform>. For example, the NSPR implementation of vpr::SocketStream is named vpr::SocketStreamNSPR. Here, <Type> is “SocketStream”, and <Platform> is “NSPR”. The full list of platform names (as spelled in the class names) is as follows:

The Input Manager itself never cares about the true type of a device. Instead, it looks at each driver as an implementation of the gadget::Input interface. This design lends itself well to a plug-in architecture wherein drivers can be loaded at runtime without being compiled into Gadgeteer. Using the Gadgeteer driver plug-in system, users can write their own device drivers without modifying Gadgeteer at all. Indeed, they need not even compile Gadgeteer from its source. All that is needed is a binary installation of Gadgeteer against which the user-written driver can be compiled.

As of this writing, there are five key device types handled by the Input Manager:

The second version of the Remote Input Manager, introduced in mid-2002, implemented input distribution by sharing devices rather than proxies, as done in the original version [Ols92]. This refactoring has changed the class hierarchy for device drivers. Previously, classes such as gadget::Digital and gadget::Position derived from gadget::Input, and device drivers used multiple inheritance to derive from one or more of gadget::Analog, gadget::Digital, etc.

With the introduction of gadget::InputMixer<S,T>, device drivers now derive from this single template class. More information will be given in Chapter 5, Writing Device Drivers, but as an example, consider a driver for a positional device. In VR Juggler 1.0 and in early versions of Gadgeteer, such a driver class would have derived from gadget::Position. Now, it would derive from gadget::InputMixer<gadget::Input, gadget::Position>. Use of gadget::InputMixer<S,T> is required if a device is to be used with the Remote Input Manager. If the old class hierarchy is used (which is still allowed), the device cannot be shared between computers.

The most obvious convention that can be seen upon review of existing device drivers is a separation of the driver code into two pieces: a standalone, “low-level” driver and a Gadgeteer wrapper around the standalone driver.

In this design, the standalone driver implements the complete hardware communication protocol without using any features of Gadgeteer. As such, it stands completely on its own and does not need Gadgeteer to be used. The result is that the driver can be tested and debugged without worrying that some part of Gadgeteer could be causing the driver to malfunction. Driver authors can focus entirely on implementing the hardware communication protocol so as to feel confident that the low-level driver is implemented correctly.

Around the low-level driver, a Gadgeteer wrapper is added. This wrapper makes use of the standalone driver interface to activate the driver and read samples. The wrapper class will derive from one or more of the Gadgeteer device types described in the section called “Device Types”. Instances of the wrapper class will be handled by the Input Manager.

As discussed in the section called “Device Types”, there are a set of abstract device types supported by Gadgeteer. Based on its capabilities, a new device will fall into at least one of the device type categories. It is perfectly valid for a single device to provide more than one type of input. For example, an Immersion Tech IBox returns both analog and digital data. Determining the device type for a new piece of hardware should be the easiest part of the driver authoring process.

The standalone device driver makes use of nothing in Gadgeteer. It can utilize dependencies of Gadgeteer including VPR and GMTL, however. Reusing code from those projects is encouraged. In particular, writing the driver on top of VPR allows it to be much more portable than it would be if all the cross-platform code were written from scratch. The reason that the standalone driver does not use Gadgeteer is so that it can be tested without needing any of the complexity of the Input Manager, thereby allowing easier, more direct debugging.

In most cases the standalone driver should be an implementation of the hardware communication protocol and nothing more. The standalone driver is written as a single C++ class that provides an interface that the Gadgeteer wrapper class can call. The interface normally has methods such as open(), sample(), and close() for opening the connection to the hardware, collecting a single sample, and closing the connection to the hardware respectively.

The standalone driver class should return data it is most raw form in the majority of cases, but the data should be meaningful. For example, if logic is needed to convert four bytes read from the hardware into a single floating-point value (a float), that should be performed in the standalone driver. That sort of data processing is part of implementing the communication protocol. However, processing such as unit conversion should not be done in the standalone driver in most cases. Instead, such conversions should be handled by the Gadgeteer wrapper class since that is where the unit configuration is done.

Typically, the standalone driver will not be multi-threaded. Instead, a method with a name such as sample() should be provided that returns a single sample. Then, test code and the Gadgeteer wrapper class can call the sampling method in a loop which may or may not be run in a thread.

With this design, the standalone driver class can be tested by writing a simple console application that makes an instance of the class and invokes each of the methods. The application can be interactive so that users can configure aspects of the driver and take samples. This makes debugging and data validation easy.

The Gadgeteer wrapper class has the job of passing samples read from the standalone driver off to the Input Manager. Depending on the device type, a given sample must be of a certain form. This is where sample buffers come into play. We will discuss sample buffers later in this section, but the possible sample buffer types are the following:

class ButtonDevice
   : public gadget::InputMixer<gadget::Input, gadget::Digital>

class JoystickDevice
   : public gadget::InputMixer<gadget::Input,
                               gadget::InputMixer<gadget::Digital,
                                                  gadget::Analog> >

namespace
{

void nonMemberSampleFunction(void* arg)
{
   ButtonDevice* dev_ptr = static_cast<ButtonDevice*>(arg);

   // Keep working until mRunning becomes false.
   while ( dev_ptr->isRunning() )
   {
      dev_ptr->sample();
   }
}

}

bool ButtonDevice::startSampling()
{
   mRunning = true;
   mThread = new vpr::Thread(nonMemberSampleFunction, (void*) this);
   return true;
}

class ButtonDevice : public ...
{
public:
   ...
   bool startSampling();
   bool sample();

private:
   static void staticMemberSampleFunction(void* arg);
   ...
};

bool ButtonDevice::startSampling()
{
   mRunning = true;
   mThread = new vpr::Thread(staticMemberSampleFunction, (void*) this);
   return true;
}

void ButtonDevice::staticMemberSampleFunction(void* arg)
{
   ButtonDevice* dev_ptr = static_cast<ButtonDevice*>(arg);

   // Keep working until mRunning becomes false.
   while ( dev_ptr->mRunning )
   {
      dev_ptr->sample();
   }
}

bool ButtonDevice::startSampling()
{
   mRunning = true;
   vpr::ThreadMemberFunctor<ButtonDevice>* functor =
      new vpr::ThreadMemberFunctor<ButtonDevice>(
         this, &ButtonDevice::membersampleFunction, NULL
      );
   mThread = new vpr::Thread(functor);
   return true;
}

void ButtonDevice::memberSampleFunction(void* arg)
{
   // Keep working until mRunning becomes false.
   while ( mRunning )
   {
      this->sample();
   }
}

bool ButtonDevice::sample()
{
   bool status(false);

   if ( mRunning )
   {
      // Here you would add your code to sample the hardware for a
      // button press:
      std::vector<gadget::DigitalData> digital_samples(1);
      digital_samples[0] = 1;
      addDigitalSample(digital_samples);

      // Successful sample.
      status = true;
   }

   return status;
}

void ButtonDevice::updateData()
{
   if ( mRunning )
   {
      swapDigitalBuffers();
   }
}

#include <gadget/Devices/DriverConfig.h>
#include <vpr/vpr.h>
#include <gadget/gadgetParam.h>

extern "C"
{

GADGET_DRIVER_EXPORT(vpr::Uint32) getGadgeteerVersion()
{
   return __GADGET_version;
}

}

#include <gadget/Devices/DriverConfig.h>
#include <gadget/Type/DeviceConstructor.h>
#include "ButtonDevice.h"

extern "C"
{

GADGET_DRIVER_EXPORT(void) initDevice(gadget::InputManager* inputMgr)
{
   new gadget::DeviceConstructor<ButtonDevice>(inputMgr);
}

}

Run-time driver registration depends on the Input Manager configuration. For our button device driver, the Input Manager would be configured to load our driver plug-in using the configuration file shown in Example 7.1, “Example Input Manager Configuration”. Here, the driver plug-in is named button_drv.so (or some other platform-specific name), and it is found in the user's home directory. Never include the _d part of the driver plug-in name or the platform-specific file extension. The Input Manager determines these details automatically, thus making the configuration files highly portable across different operating systems. For more details about how to configure the Input Manager, refer to the VR Juggler Configuration Guide.

<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings configuration.version="3.0"?>
<configuration
  xmlns="http://www.vrjuggler.org/jccl/xsd/3.0/configuration"
  name="Configuration"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.0/configuration http://www.vrjuggler.org/jccl/xsd/3.0/configuration.xsd">
   <elements>
      <input_manager name="Button Device Input Manager" version="2">
         <driver_path>${HOME}</driver_path>
         <driver>button_drv</driver>
      </input_manager>
   </elements>
</configuration>

Every Gadgeteer device needs a unique element type associated with it. An element type is similar to a struct in C or C++. The data structure is defined in an configuration definition file (which usually has the extension .jdef). Once defined, the type for a new driver can be used in JCCL configuration files.

Therefore, a new driver-specific configuration definition must be created before a driver can be configured. We recommend that this be done using the VRJConfig Config Definition Editor. For the button device, the definition file is shown in Example 7.2, “button_device.jdef: Configuration Definition File for Simple Button Device”.

Example 7.2. button_device.jdef: Configuration Definition File for Simple Button Device

<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings definition.version="3.1"?>
<definition xmlns="http://www.vrjuggler.org/jccl/xsd/3.1/definition"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.1/definition http://www.vrjuggler.org/jccl/xsd/3.1/definition.xsd"
            name="button_device">                               
   <definition_version version="1" label="My Button Device">
      <help>Configuration for simple one-button device.</help>
      <parent>digital_device</parent>                           
      <category>/Devices/Digital</category>
      <property valuetype="string" variable="false"
                name="port">                                    
         <help>Serial port the device is connected to.</help>
         <value label="Port" defaultvalue="/dev/ttyd1"/>
      </property>
      <property valuetype="integer" variable="false"
                name="baud">                                    
         <help>Serial port speed.</help>
         <value label="Baud" defaultvalue="38400"/>
      </property>
      <upgrade_transform/>
   </definition_version>
</definition>

	This begins the definition for our device type. The name attribute must be named as a valid XML tag (a CNAME in XML terminology) because it will be used as such in a configuration file. A free-form, human-friendly string may be specified in the label attribute of the definition_version element. This string will be presented to the user of VRJConfig, and as such, it should be a meaningful identifier.
	The parent (or base type) for this config definition. Zero or more of these are allowed. In this case, we must indicate that digital_device is a parent type so that VRJConfig will know that digital proxies can be pointed at config elements for our driver. We also inherit property definitions from digital_device including “device_host”, which is needed for cluster configurations.
	This declares the “port” property that will provide the name of the serial port to which the hardware is connected. The serial port name will be interpreted as a string, and it has the default value of “/dev/ttyd1”. In the case of our simple button driver, there is no serial port, but we include this property definition to demonstrate how the whole configuration definition works.
	This declares the “baud” property that will provide the baud setting for the serial port to which the hardware is connected. The baud value will be interpreted as an integer, and it has the default value of 38400 (kilobits per second). In the case of our simple button driver, there is no serial port, but we include this property definition to demonstrate how the whole configuration definition works.

For a more complex device, a more complex configuration definition may be needed. Again, the VRJConfig Configuration Definition Editor simplifies the creation of this definition.

Once the configuration definition is in place, a new configuration element can be created. Once again, VRJConfig makes the step easier. In Example 7.3, “button_device.jconf: Configuration File for Simple Button Device”, we see a configuration file that configures the one-button device we have been using thus far.

<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings configuration.version="3.0"?>
<configuration xmlns="http://www.vrjuggler.org/jccl/xsd/3.0/configuration"
               name="Configuration"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.0/configuration http://www.vrjuggler.org/jccl/xsd/3.0/configuration.xsd">
   <elements>
      <input_manager name="Button Device Input Manager"
                     version="2">                             
         <driver_path>${HOME}</driver_path>
         <driver>button_drv</driver>
      </input_manager>
      <button_device name="Button Device" version="1">        
         <port>/dev/ttyd4</port>                              
         <baud>9600</baud>                                    
         <device_host />                                      
      </button_device>
      <digital_proxy name="Button Proxy 0" version="1">       
         <device>Button Device</device>
         <unit>0</unit>
      </digital_proxy>
      <alias name="VJButton0" version="1">
         <proxy>Button Proxy 0</proxy>
      </alias>
   </elements>
</configuration>

	The input_manager element configures the Gadgeteer Input Manager. In this case, we are telling the Input Manager about a driver plug-in, found at ${HOME}/button_drv.so, that should be loaded at run time. Tip Earlier, we introduced the Input Manager configuration in a separate configuration file. In general, we recommend configuring a given device entirely within one .jconf file—including the input_manager config element that loads the driver plug-in. That is precisely what we are showing in this example.
	Next, we have an instance of the configuration definition shown in Example 7.2, “button_device.jdef: Configuration Definition File for Simple Button Device”. As described above, <button_device> is named based on the name attribute of the definition element in our configuration definition file. The name attribute here gives this instance a unique identifier.
	Now, we set the value for the serial port name. As noted above, our simple button device does not actually use the serial port, but this demonstrates how the property value is used in a configuration file. If no value were given here, the default value set in button_device.jdef would be used.
	This provides a value for the serial port baud setting. Again, this will not actually be used by our simple device, but we show it here to give a complete example.
	For our example, we will not fill in a value for device_host because we are not dealing with the Remote Input Manager. Refer to the VR Juggler Configuration Guide for more information about this.
	Finally, we point a digital proxy at our device. Since the device has only one input source, we have to use 0 for the unit value.

In the driver, recall that there are two methods that must be implemented in order to handle config elements:

We now present these two methods, thereby completing the interface of the driver as far as the Input Manager is concerned.

std::string ButtonDevice::getElementType()
{
   return std:string("button_device");
}

bool ButtonDevice::config(jccl::ConfigElementPtr e)
{
   // Configure all our base classes first.  If any of those fail,
   // we cannot finish configuring ourself.
   if ( ! gadget::Input::config(e) && ! gadget::Digital::config(e) )
   {
      return false;
   }

   mPortName = e->getProperty<std::string>("port");
   mBaudRate = e->getProperty<int>("baud");

   return true;
}