Liquid: Adding Sensor Classes

ADDING SENSOR CLASSES - VERSION 1.0

Preface

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 (see Output Descriptors for Developers).

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).

INFO: The component-based architecture of Liquid which is suppose to allow the toolkits sensor library to be extended has not yet been fully finalized (as of version 1.0). Therefore some elements of the upgrade process may involve hard-coding them into Liquid, the Liquid Device Driver (LDD) and the Liquid Client Application (LCA).

TO ADD A NEW CLASS

The process of adding a new sensor class to the toolkits library involves 3 stages:

STAGE 1: UPDATING CLASS.INI

Liquid uses the ini file class.ini to describe the menu layout of the sensor selection process. The class.ini file format is as follows:

[INFO]
version= X.X //Liquid version (floating point number)

[PURPOSES] //under this section key all the applicable sensor purposes should be listed
supported = //no. of sensor purposes listed
purpose0 = //sensor purpose (N value provides the first value of the PPM key, see further on)
purpose1 =
purpose2 =
purposeN =

[PURPOSE0] //under this section key all the applicable properties for this purpose should be listed
supported = //no. of properties listed
property0 = //property measured (N value provides the second value of the PPM key, see further on)
property1 =
propertyN =

[PURPOSE 0 : PROPERTY0]

//under this section key all the applicable means of sensing for this purpose-property combination should be listed

supported = //no. of means listed
means0 = //means of sensing (N value provides the third and final value of the PPM key, see further on)
meansN =
. . . . .

To add a new entry simply follow the given file format, remember to increment the N value of the purpose, property or means key before listing it e.g. if only 1 property currently existed the next key would be listed as property1=" ". When creating a new purpose and/or property section key it must be written in CAPTIALS surrounded by square brackets []. Below is an example of a completed class.ini file:

[INFO]
version= 1.0

[PURPOSES]
supported = 1
purpose0 = Occupancy Detector

[OCCUPANCY DETECTOR]
supported = 1
property0 = Infra Red

[OCCUPANCY DETECTOR : INFRA RED]
supported = 2
means0 = IR Sensor (Switch)
means1 = IR Sensor (Thermal)

On creating a new sensor class a unique 3 number key will be generated called the PPM key. This key is used by the toolkit to identify the PPM combination throughout its hierarchy (Liquid, LDD, LCA). For instance in the example above the PPM combination Occupancy Detector-> Infra Red->IR Sensor (Thermal) will use the key 0 0 1. You will need to remember this key in order to finish this tutorial.

WARNING: Do not change any of the key values that currently exist in the class.ini file. Although the output format the sensor class uses is stored in the LDD instead of Liquid, changing key values will distort the menu system (sensors will be grouped under the wrong PPM headings, although they will still be displayed correctly when activated).

STAGE 2: UPDATING FORMAT.INI

Liquid uses the ini file format.ini to describe the value of the constraint parameters for each sensor classes output format. Consult Output Descriptors for Developers to see if the output format your sensor should be using has already been catered for.

If the required output format is not supported by the current version of Liquid turn to Adding Output Formats and Adding Visualization Modes before continuing this tutorial. If the required output format does not support any parameters move onto stage 3. format.ini files format is as follows:

[INFO]
version= X.X //Liquid version (floating point number)

[PURPOSEN : PROPERTYN : MEANSN] //PPM combination (section key)
. . . . . //constraint values (see Output Descriptors for Developers for parameter names)

To add a new entry, create a section key using the PPM names used in class.ini (do not use the PPM key). List the constraint parameters and their respective values under the generated section key. When creating a new purpose : property : means section key it must be written in CAPTIALS surrounded by square brackets []. Below is an example of a completed format.ini file:

[INFO]
version=1.0f

[OCCUPANCY DETECTOR : INFRA RED : IR SENSOR (THERMAL)]
unit=Fahrenheit
rr_min=-4
rr_max=3600
mr_min=-4
mr_max=3600
percentage=FALSE

WARNING: Do not change any of the key values that currently exist in the format.ini file. If any mistakes are made with the spelling of the section key, Liquid will display an error informing the user it could not find the sensors constraint parameters.

STAGE 3: UPDATING SENSOR CODES.H + UTILITIES.H

The toolkits hierarchy (Liquid, LDD, LCA) use the source file Sensor Codes.h to define the supported sensor classes. Open a copy of the file Sensor Codes.h and following the below file format add your PPM key to the list:

#define PURPOSE P       //assign definition first value of the PPM key

#define PE_PROPERTY P   //assign definition second value of the PPM key

#define PEPY_MEANS M    //assign definition third value of the PPM key

Property definitions should always be written beginning with a unique combination of characters (2 chars long) that indicate the purpose it belongs to, directly followed by an underscore character '_' (would typically use the first and last character of the purpose definition).

Means definitions should always be written beginning with a unique combination of characters (4 chars long) that indicate the purpose it belongs to followed by a combination of characters indicating the property it is associated with, directly followed by an underscore character '_'.

Below is an example Sensor Codes.h file:

#define SYSTEM_TEST 0 //ST taken as purpose id
#define ST_SYSTEM_STATUS 0 //STSS taken as purpose-property id
#define STSS_TEST_PROGRAM 0

Now if we have a sensor class with the PPM key 0 1 0 (System Test -> Seek Time -> Test Program) the file would look like this:

#define SYSTEM_TEST 0 //ST taken as purpose id

#define ST_SYSTEM_STATUS 0 //STSS taken as purpose-property id
#define ST_SEEK_TIME 1 //STST taken as purpose-property id

#define STSS_TEST_PROGRAM 0

#define STST_TEST_PROGRAM 0

Utilities.h provides a series of functions to help identify the meaning of certain system codes/definitions. The methods getPurpose(..), getProperty(..) and getMeans(..) require updating in order to identify the new sensor class. Each method is structured in the following format:

static char *get__(int definition)
    {
    switch (definition)
        {
        case A:   return "A";
        case B:   return "B";
        case C:   return "C";
        default: return "Unknown Code";
        }
    }

Add the definition names of your sensor class to each of the 3 methods followed by a description of the PPM element itself. Taking the previous cited example of Sensor Class.h the methods would be written as follows:

static char *getPurpose(int definition)
    {
    switch (definition)
        {
        case SYSTEM_TEST:   return "System Test";
        default: return "Unknown Code";
        }
    }

static char *getProperty(int definition)
    {
    switch (definition)
        {
        case ST_SYSTEM_STATUS:   return "System Status";
        case ST_SEEK_TIME:       return "Seek Time";
        default: return "Unknown Code";
        }
    }

static char *getMeans(int definition)
    {
    switch (definition)
        {
        case STSS_TEST_PROGRAM:   return "Test Program";
        case STST_TEST_PROGRAM:   return "Test Program";
        default: return "Unknown Code";
        }
    }

After updating Sensor Codes.h and Utilities.h* distribute it to all other members of the toolkit hierarchy and recompile the project spaces. Your sensor class is now ready for use.

INFO: * The methods cited for change are not used by the Liquid application. Liquid is capable of identifying a sensor class from its definition codes by making use of the file class.ini (class.ini is a reflection of the source file Sensor Codes.h, hence why you shouldn't alter any of the existing key values). The purpose of updating Utilities.h is for the benefit of LCA's because they will not be capable of accessing this file.

. . back to Manual Index