HOW TO BUILD A LIQUID CLIENT APPLICATION - VERSION 1.0

Preface

Liquid supports the development of prototype sensor-based applications via its development studio (DS). The DS works in a similar fashion to the file transport protocol (FTP). Separate ports are employed to facilitate both command & control functions (C&C server) and the transfer of sensory data (OUTPUT server).

A Liquid Client Application (LCA) is designed to connect to these servers in order for it to manipulate and make use of the sensor and the data it collects in any way it sees fit.

GETTING STARTED

Download the template LCA from the following web page http://sensors.comp.lancs.ac.uk/liquid/downloads.html. The template already contains all the necessary code to facilitate a connection to the DS servers and begin sensor manipulation (includes the collection of selected sensors input and outputting it to a dialog box launched by the LCA).

All that is required is adjusting the LCA to your requirements. This manual provides only the most basic information about creating an LCA because the template already contains all the necessary code and advice on building one.

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

TEMPLATE LCA PROJECT SPACE

The template LCA project space is laid out as follows:

COMMUNICATION PROTOCOL

Communiqués between the DS and the LCA follow a strict sequence. Before developing your own LCA it would be worthwhile memorizing this order of events however it is not essential because the template is designed to run the protocol automatically after connecting.

SETTING UP

The DS C&C and OUTPUT servers are activated (see here) establishing themselves on ports 100 and 101 respectively. The LCA launches a C&C and OUTPUT client which will establish a connection to the respective DS servers via a TCP connection.

SESSION SIZE

The DS C&C server posts the session size (number of sensors being used) to the LCA C&C client.

SENSOR IDS

The DS C&C server posts the sensor ids to the LCA C&C client. An id consists of the sensors driver details (version, sensor class, model name) and its output type. Each sensor id is posted separately in 2 stages, first the sensors driver details are posted followed by its output type.

The order the sensor ids are returned in is the order sensory data will be returned in.

WAITING ON YOU

C&C is passed to the LCA. DS C&C server waits for commands to be posted.

C&C SERVER

The purpose of the C&C server is to facilitate C&C of the session sensors. Once the LCA has connected to the DS servers and received all the relevant details about the sensors, both the DS C&C server and LCA C&C client initiate a command interpreter.

Once the command interpreter is executed the LCA C&C client is capable of making several decisions:

1. Activate - activates the sensors / un pauses
2. Deactivate - deactivates the sensors / pauses
3. Close - shuts the sensors down

Whenever an option is selected a communiqué is posted from the C&C client to the C&C server. If the selected option is valid the C&C server will execute the command. After the command has been completed server side a success boolean (TRUE or FALSE) is returned (excludes close command) and the C&C client instigates the necessary code to facilitate the success of that command e.g. if the sensors were successfully activated the OUTPUT server would of been activated, therefore the C&C client needs to activate the OUTPUT client in order to receive sensory data.

INFO: The 'open' command is executed as part of the DS setup.

OUTPUT SERVER

The purpose of the OUTPUT server is to facilitate the transfer of the collected sensory data. Once the LCA has connected to the DS servers and received all the relevant details about the sensors, both the DS OUTPUT server and LCA OUTPUT client will pause and wait for instructions from their respective C&C counterparts.

Data collection and its transfer to the LCA can only begin when the activate command is received by the C&C server. On receivership the OUTPUT server will begin collecting input from the sensors and forwarding it to the OUTPUT client. Each sensors input is posted separately in 2 stages, first the byte size of the incoming sensory data is posted followed by the actual data itself.

If an error has been encountered by the OUTPUT server the byte size will read as an EXIT CODE (these are always negative). The template automatically converts the EXIT CODE to a string using the functions provided in Utilities.h.

Data is continually streamed to the OUTPUT client until either the deactivate or close command are posted to the C&C server.

When the deactivate or close command is received the C&C server will inform the OUTPUT server to send the remainder of the sensory data it is to collect (every cycle of the OUTPUT server involves the collection and posting of sensory data for every sensor exactly once) and wait for further instructions (pause). Once the remaining sensory data has been posted the C&C server will inform the C&C client that the command was completed successfully.

If the deactivate command was called the OUTPUT client will be instructed to wait, if the close command was called the OUTPUT client will be instructed to exit so the LCA can close safely.

INFO: More detailed error descriptions are outputted via the DS message box.

LCA VARIABLES

Below is a description of the key variables that the template uses to manipulate the C&C and OUTPUT clients. They are located in the source file Device Driver.cpp (although their struct definitions may be located in either Device Driver.h or Utilities.h.

VIEWING + MANIPULATING SENSORY DATA

Consult Output Descriptors for Developers on how your sensors input stream will be returned by the OUTPUT server. The necessary code to retrieve sensor readings (for the sensors supported under Liquid version 1.0) has already been inserted in the source file Client.cpp.

ADDITIONAL HELP

For further information on building an LCA, download the pilot alarm LCA from the downloads page.

. . back to Manual Index