EPSIAE » eneraptor

h1. Human Computer Interaction

{{toc}}

h2. 1 Basic concept

h3. 1.1 Hardware

p. The HCI will will be realised as a website. It will run on an Apache Tomcat http server, which will not run on the same device as Eneraptor's logic. Instead it will run on an independent proxy server.

p=. !HMI_website_overall.png!

p. The intended server-side html generating aplication is Tomcat's Jasper, making JSP the intended website programming language.

h3. 1.2 HCI features

The picture below shows basic HCI features:

!HCI_basic.png!

h2. 2 Communication with other parts

h3. 2.1 Logged data (instructions for syslog dev)

All logged data has to be written in a *PostgreSQL* database. Database's name must be *eneraptor-db*. Data must be writen in *standard public schema* (default).

The database table will exist prior to logging unit's (Janez) first run, so logging unit does not need to create the table. The logging unit *must* know, how to add a log entry to the database correctly, so that HCI will be able to use this data:

Every new log entry should be added with the following SQL query:

<pre>

INSERT INTO logged_data(

            id, "version", date_recieved, device_id, reported_data)

    VALUES (nextval('hibernate_sequence'), 0, now(), 'enterDeviceIdHere', 'enterReportedDataHere');

</pre>

enterDeviceIdHere and enterReportedDataHere should be replaced with actual data. Logging unit *must not* change other parts of the SQL query above.

While developing the logging unit (Janez) it may be useful to have a test database like the one HCI will create in the final product. You can create such a database with the following SQL query:

[[createEneraptorDatabase.backup]]

h3. 2.2 Getting info from the logic unit (instructions for DMS dev)

Every time HCI wants to get any information from the logic directly, it establishes a TCP connection (using sockets). The logic unit should use a socket to listen to a port for an incoming connection.

When a connection is established, HCI sends a series of lines that together represent some XML data and waits until the logic unit sends some XML data back. The connection is then closed. The root node of HCI's request will always be:

<pre><code class="xml">

<hci-request type="...">

   ...

</hci-request>

</code></pre>

The _type_ attribute value may be one of the following: checkConnection, getConfig, setConfig, getActions, setActions, executeAction.

| *type* | *purpose*                                                    | *what HCI expects in the reply*                 |

| @checkConnection@ | a simple echo for testing connectivity            | echoed data                                     |

| @getConfig      @ | HCI gets current logic's configuration            | logic's current configuration                   |

| @setConfig      @ | HCI sends new configuration to the logic unit     | confirmation that new config was accepted       |

| @getActions     @ | HCI gets a list of actions                        | logic's currently installed actions             |

| @setActions     @ | HCI sends a new list of actions to the logic unit | confirmation that new actions list was accepted |

| @executeAction  @ | HCI demands executing an action instantly         | confirmation that the action has been executed  |

h4. 2.2.1 The @checkConnection@ protocol

This performs a simple test to check, if the connection between HCI and the logic unit can be established succesfully.

The check connection request has the following structure:

<pre><code class="xml">

<hci-request type="checkConnection">

   <data>

      INTEGER_VALUE

   </data>

</hci-request>

</code></pre>

Example:

<pre><code class="xml">

<hci-request type="checkConnection">

   <data>

      123456

   </data>

</hci-request>

</code></pre>

Logic's response shoud have the following structure:

<pre><code class="xml">

<logic-response type="checkConnection">

   <data>

      INTEGER_VALUE

   <data>

</logic-reply>

</code></pre>

Example:

<pre><code class="xml">

<logic-response type="checkConnection">

   <data>

      123456

   <data>

</logic-reply>

</code></pre>

The same value of @INTEGER_VALUE@ in the request should be returned in the response.

h4. 2.2.2 The @getConfig@ protocol

This is used for obtaining current logic configuration. HCI then may change it and send it back using @setConfig@ request.

HCI's request is static:

<pre><code class="xml">

<hci-request type="getConfig">

</hci-request>

</code></pre>

Logic's response should have the following structure:

<pre><code class="xml">

<logic-response type="getConfig">

   <setting id="settingId1">

      <label>Setting 1 label</label>

      <desc>Setting 1 description</desc>

      <type>SETTING_TYPE</type>

      <value>SETTING_VAL</value>

   </setting>

   ...

</logic-reply>

</code></pre>

SETTING_TYPE may take one of the following values: byte, short, int, bool, string, float, double.

SETTING_VAL must be either a numer (for byte, short, int, float and double types), a string (for string type) or 'true' or 'false' (for bool type).

The setting's id attribute may be anything. HCI doessn't need to know which settings exist in the logic - the configuration form gets generated from this reply.

Example:

<pre><code class="xml">

<logic-response type="getConfig">

   <setting id="loggingOn">

      <label>Logging active</label>

      <desc>Sets logging on or off</desc>

      <type>bool</type>

      <value>true</value>

   </setting>

   <setting id="ignoreAllMeasurements">

      <label>Ignore measurements</label>

      <desc>Suspends decision making software by ignoring all measurements</desc>

      <type>bool</type>

      <value>false</value>

   </setting>

</logic-reply>

</code></pre>

h2. References

# Chopra, Vivek, et al., _Professional Apache Tomcat 6_, Wrox - Wiley, 2007

# Basham, Bryan, et al., _Head First Servlets and JSP™_, O’Reilly, 2008

h2. Attachments