HOW TO BUILD A LIQUID DEVICE DRIVER - VERSION 1.0

Preface

Liquid supports sensors via API wrappers known as Liquid Device Drivers (LDD). An LDD encompasses the often complex code necessary to manipulate a sensor within a small command set.

GETTING STARTED

Download the template LDD from the following web page http://sensors.comp.lancs.ac.uk/liquid/downloads.html. The template LDD already contains all the necessary code to run the wrapper under Liquid, all that is required is some minor code configuration and the completion of several driver methods.

INFO: The template LDD source files are written in C and are provided with a VC++ 6 Project File.

TEMPLATE LDD PROJECT SPACE

The template LDD project space is laid out as follows:

DRIVER DEFINITIONS

The LDD definitions are used to describe the drivers purpose and capabilities to Liquid. They are located in the source file Device Driver.cpp.

LIQUID VERSION

To define the version of Liquid your driver is designed for, set the definition LIQUID_VERSION to the applicable value (floating point number). The template LDD is always set to the current version of Liquid available.

INFO: Liquid is backwards compatiable with all drivers earmarked for earlier versions of itself.

DRIVER VERSION

To define the driver version, set the definition DRIVER_VERSION to the applicable value (floating point number).

SENSOR CLASS

The sensor class describes how the sensor should be categorized in relation to others. Sensors of an identical class will always return input in an identical format.

A sensor class is made up of 3 attributes, the sensors primary purpose, the property measured by the sensor and the means of detecting that property (referred to as the PPM combination). To identify which class your sensor belongs to consult Supported Sensor Classes. If your sensor does not fall into any of the supported classes consult Adding Sensor Classes.

To define the sensor class, set the definitions PURPOSE_OF_SENSOR, PROPERTY_MEASURED and MEANS_OF_SENSING to the applicable values. Consult Supported Sensor Classes or the Sensor Codes.h source file for class values.

SENSOR MODEL

To define the sensor model, set the definition SENSOR_MODEL to the applicable string.

INFO: The sensor model definition is used to populate the model box during the sensor selection process (see here).

OUTPUT TYPE

Defines the form sensor input should take on returning to Liquid e.g binary, numeric, image, etc. To identify which output type your LDD should be using consult Output Descriptors for Developers.

To define the output type, set the definition OUTPUT_TYPE to the applicable value. Consult Output Descriptors for Developers or the Device Driver.h source file for type values.

MODULE NAME

The module name defines the file name of the driver. It is used to locate the dialog resources stored in the driver. To define the module name, set the variable moduleNAME to the applicable string.

WARNING: An incorrect module name will cause the driver to work in an errounous fashion. However it will not generate an error in itself.

DRIVER METHODS

The LDD methods are used to retrieve information regarding the sensor and command its operation. They are located in the source file Device Driver.cpp.

There is a total of 15 methods to be found in an LDD, 9 of which need to be configured for the sensor being supportred. Below is a brief description of each of these 15 methods, for more detailed information consult the comments that accompany each method in the source file Device Driver.cpp. Methods that require configuration are emphazied using .

INFO: The comments that exist in the source files are meant to act as guide and do not necesarly need to be followed to the letter with regards to placing code.

METHOD 1: isLiquidDriver()

First method called by Liquid, used to identify the .dll as a valid LDD.

METHOD 2: getLiquidVersion()

Returns the Liquid version the LDD was designed for.

METHOD 3: getDriverDetails(...)

Returns the following details, driver version, sensor class attributes (PPM) and sensor name.

METHOD 4: getOutputType()

Returns the output type the LDD uses.

METHOD 5: getSensorStatus()

Returns the sensors runtime status. Runtime codes are as follows:

METHOD 6: openSensor(...)

Initializes the sensor (switches it on). openSensor(...) accepts the following arguments:

The window handle is used to lock the Liquid GUI when a dialog box is summoned from the LDD (prevents further instances of the dialog being created).

The min and max limits define the acceptable input range, if sensor readings fall outside this range and no error has been detected return the exceeded limit value e.g. if the acceptable range was 0-20 units and input was 21 return the value 20.

The percentage flag indicates whether input should be returned as a percentage of its maximimum value. The DOS flag indicates if the driver is being run by the DEVICE DRIVER TEST PROGRAM or Liquid.

Insert the necessary initialization code into the place indicated by the method comments. If the sensor allows user configuration make use of methods 11 and 14 (launched by the command int code=configSensor(hWnd)) . Method 11 launches a dialog box which can be tailored to provide all the neccessary configuration faciliates to the user. Method 14 is the dialogs message handler and should be used to extract the configuration chosen by the user. This information can then be employed to initialize the sensor as the user requires.

The configuration dialog is stored in the source file resources.rc, its system name is IDD_SENSORCONFIG. A minimal configuration dialog has already been implemented for your convience.

If no configuration is required set method 11 to return the definition NO_CONFIG_REQUIRED.

METHOD 7: closeSensor()

Shuts the sensor down (switches it off, closing all applicable handles to the sensors API). Insert the necessary shut down code into the place indicated by the method comments.

Remmeber to reset any variables that were previously set during initialization of the sensor.

METHOD 8: activateSensor()

Activates input collection (unpauses input collection if previously deactivated). Insert the necessary activation code into the place indicated by the method comments.

METHOD 9: deactivateSensor()

Deactivates / pauses input collection. Insert the necessary deactivation code into the place indicated by the method comments.

METHOD 10: getSensorInput()

Returns sensor input in the specified output format. Insert the necessary retrieval and conversion code into the place indicated by the method comments. Consult Output Descriptors for Developers on how your sensors input stream should be formated.

METHOD 11: configSensor(...)

Configures the sensor (launched via METHOD 6). Designed to execute a configuration dialog box if user configuration is to be allowed. If no user configuration is to be allowed or required return the definition NO_CONFIG_REQUIRED. Insert the necessary configuration code into the place indicated by the method comments.

The configuration dialog is stored in the source file resources.rc, its system name is IDD_SENSORCONFIG. A minimal configuration dialog has already been implemented for your convience.

METHOD 12: sensorHelp(...)

Executes a help dialog box. The help dialog should provide all the necessary information to help the user run and configure the sensor. If no user help is to be provided return the definition NO_HELP_AVAILABLE.

The help dialog is stored in the source file resources.rc, its system name is IDD_HELP. A minimal help dialog has already been implemented for your convience.

METHOD 13: getLastError()

Returns a description of the last error encountered. When an error is generated by the driver the applicable error code is to be returned (see source file Device Drivers.h for supported codes and their meanings). However these codes do not carry sufficent enough information in themselves to attempt a fix.

Therefore whenever an error is encountered set the global variable char* error_message to a more relevant description of the problem. When an error is generated this method will be called by Liquid to retrieve a more descript definition of the problem.

METHOD 14: ConfigProc

Handles the dialog messages received by the configuration dialog IDD_SENSORCONFIG. Insert the necessary code to extract the configuration chosen by the user. A minimal message handler has already been implemented for your convience.

METHOD 15: HelpProc

Handles the dialog messages received by the sensor help dialog IDD_HELP. Insert the necessary code to provide sensor help. A minimal message handler has already been implemented for your convience.

INFO: In the majority of cases one simply has to change the variable char text[] to a meaningful help string.

EXIT CODES

Always return the applicable exit code at the end of methods 6-12 . Exit codes are listed under the heading EXIT CODES in the source file Device Driver.h, below is a summary of the supported error codes:

If a method executed successuly and exit codes such as NO_CONFIG_REQUIRED do not apply always return TRUE. Consult the method comments on the applicablity of the exit codes.

COMPILING

Before compiling your LDD set the output name to the module name, otherwise Liquid will be unable to locate any of the dialog resources. An LDD is modelled as a dynamic link library and so the output name should always end with the .dll extension. On compiling the LDD 2 files will be generated, a .lib and .dll file. Liquid is only interested in the .dll file, so the .lib file can be deleted (this would only be used if Liquid was to have explict knowledge that the .dll existed).

To test your LDD for errors use the LDD Test Program. Once you are happy with your LDD, it is ready for general use! Copy it into the drivers folder of the Liquid application directory and launch Liquid to use it, if you need help in running Liquid consult the Toolkit Operating Manual.

RELEASING YOUR DRIVER

Liquids usuability is entriely dependant on the support it receives from 3rd party developers such as yourself in creating and releasing add-ons to its sensor library. You can post new drivers to the Liquid site care of this email

INFO: If your sensors API requires installing before the LDD will run make sure to inform the user before releasing the driver.

. . back to Manual Index