EPSIAE » eneraptor

h1. The logic

{{toc}}

h2. Basic concept

System Eneratptor is designed to take predefined actions in response to events in the surrounding world. The logic system is designed to be easily calibrated and managed. In addition to its predefined logic it allows the human administrator (through HMI) to reverse any automated or scripted decision and to execute any of the predefined actions, thus allowing the operator to tweak the system according to her best judgement.

!Logika.jpg!

The logic of the system consists of the following concepts:

* Device maneger

* Mailbox

* Decision making software

* Predefined action list

* Action

* [[Human Machine Interface]]

The basic idea behind this design is modularity. Eneraptor supports any device and can execute any action as long as the driver follows our standard. In this scenario we [the eneraptor designers] expect the device manufacturer (ie air conditioning unit) at least two supply two _programs_ : the device manager and the action program. If there are several actions supported by the device, we expect each to be a standalone program or all actions to be in a single program targeted by different command line arguments.

h2. Concepts described in detail

h3. Device manager

Device manager is basically a program. The eneratptor system doesn't know anything about it, the only crucial part is the driver-mailbox communication through witch data is supplied. More about date in the _message specification_. The device manager has to know how to reach the mailbox and how to correctly format the message. The device manager does not receive any confirmation from the message recipient.

This driver is not necessarily the same software which is supplied by the manufacturer, it is only a program that communicates with the eneratpr Mailbox.

h3. Mailbox

Mailbox is a bridge between the device managers and the decision making software. It is a buffer of messages that the decision making software can read at its own pace.

*The design of the mailbox and message structure is still open to debate; all input is welcome!*

The mailbox should be event driven, meaning no periodic checking is necessary. The device manager will signal the control program which will in turn read the shared variable for data.

h3. Decision making software

Decision making software is the key mechanism of the eneraptor project. It brings all other components together to ensure all conditions set by (human) operators are met.

The decision making software continuously checks the mailbox for new messages. If any new info is read the software compares it with all the predefined conditions (see _predefined action list_). If a condition is met, the action is executed. If several conditions are met, all co-responding actions are executed.

This (very elegant) main loop is always executing, however it can be halted by the [[Human Machine Interface]]. When this happens the loop still executes, however all but the messages originating from HMI are ignored.

h3. Predefined action list

Predefined action list is a list of all the conditions and co-responding actions entered to the system. It is implemented as a non-ordered list of structures containing the information: 

# Input device ID

# Corner value

# Comparison operator

# Action to be executed

The list is saved in a csv/xml file. It is initialized with on the Decision Making Software program startup and then periodically refreshed, insuring no restart is required when additional rules are entered.

h3. Action

Action is a program path and program argument pair, thus allowing the _Decision making software_ to execute it.

There are several rules for the Action developers:

* The Action program must be executable through command line,

* The Action program must *not* expect human interaction,

* The Action program must terminate in a deterministic time,

Outside of this very general rules the Action developers have no limitations in writing the Action programs.

h2. Communication and message formats

The logic component uses three types of messages to connect to other parts of the Eneraptor system. They are the following:

* The message for communication with device manager -> XML

* The message for communication with HMI -> XML

* The message for logging (via syslog) -> formatted plain text

These messages are then transported over the network to their destination.

* The Logic -> device manager communication uses *IP sockets* to relay messages.

* The Logic <--> HMI communication uses *UDP* communication to relay messages.

* The Logic <--> Logging service uses system logger for logging messages. Relaying is done by syslog-ng.

h3. The logic <--> device manager message

The device manager logic is twofold: when the device manager signals new available data, it is read from a shared variable (encapsulated within a monitor). The IP socket is used for the reverse connection, when the HMI request a certain value which has to be read. When that happens a +request message+ is sent. The messaging thread blocks until an answer is received. The response is then transformed to Logic -> HMI message and sent to HMI.

The syntax of the request message is irrelevant since the there aren't several data points to choose from. The response however should be a single double value (defined with IEEE 754).

*Questions:*

* Will there ever be a device manager with several data points available for reading?

*Notes:*

* The named pipe option was considered however I prefer the IP socket protocol. The main reason behind this decision is that a named pipe can only be open for reading *or* writing thus complicating the programming somewhat.

h3. The logic <--> HMI message

> Alex B. proposal:

>

> There should exist three types of messages used for communication between the logic and HMI, depending on how should the logic react after receiving a message:

> * Type1: HMI requests for some information; logic replies.

> * Type2: HMI requests for a change in logic's configuration; logic reacts; logic sends a message confirming changes have been succesfully (or unsucsessfully) applied.

> * Type3: HMI wants to add or change a new acion

>

> The first message type from HMI could looke like this:

> <pre><code class="xml">

<hmi-request>

   <device-stat>

      <device id="Thermometer_01" />

      <device id="Moisture_meter" />

   </device-stat>

   <config-stat>

      <config id="startup_time" />

      <config id="logging-enabled" />

   </config-stat>

</hmi-request>

  </code></pre> 

>

> And the logic's response could look like this:

> <pre><code class="xml">

<logic-response>

   <device-stat>

      <device id="Thermometer_01">

         <value>24</value>

      </device>

      <device id="Moisture_meter">

         <error type="device_controller_returned_1" />

      </device>

   </device-stat>

   <config-stat>

      <config id="startup_time">08:25:22 22/12/2010</config>

      <config id="logging-enabled">true</config>

   </config-stat>

</logic-response>

  </code></pre>

>

> The second type of HMI's request could look like this:

> <pre><code class="xml">

<hmi-request>

   <config>

      <config id="logging-enabled">false</config>

   </config>

</hmi-request>

  </code></pre> 

>

> And the response could look like this:

> <pre><code class="xml">

<logic-response>

   <config>

      <config id="logging-enabled">success</config>

   </config>

</logic-response>

  </code></pre>

>

> The third message type from HMI could look like this:

> <pre><code class="xml">

<hmi-request>

  <todo>

</hmi-request>

  </code></pre> 

>

> And the response could look like this:

> <pre><code class="xml">

<logic-response>

  <todo>

</logic-response>

  </code></pre> 

>

> Of course all three types of messages could be joined in a single XML file _if_ this would be useful (?).

h3. The logic -> logging

The logic uses syslog to save a plain text message to the database. However the message has to be formatted, so the information can be extracted by the Statistical Data Analysis Software ([[Archive and statistics]]. 

The archiving can be initiated for the following reasons:

* Type1: New data was sent by the device manager,

* Type2: Action was taken due to the read changes in the observed world,

* Type3: Action was initiated by the system administrator via HMI.

The reason for the archiving has to be visible in the message. Thus the first byte of the message is reserved for the type of the message. The rest of the message is conditioned by the type. The first byte is followed by:

h4. Type1

* The new data received, saved in a single double value (IEEE 754).

h4. Type2

* The action taken (id of the action saved in a single short int value)

h4. Type3

* The action taken (id) followed by the system administrator id.

*Questions:*

* Should the files be human readable or should they be just a data stream?

* Is the datetime part of the log written automatically by the syslog? (The above data structures assume so).

* Did I forget any vital information? 

h2. Configuration

The configuration consists of a XML file, which is read on startup. The XML file should look like this:

<todo>

The configuration can also be modified by the HMI. When that happens the XML configuration file has to be modified to reflect the new changes.

h2. The interfaces

The following interfaces have to be defined by the extern components for them to be seen as a valid Eneraptor component:

<todo>

h2. Logic separation to parts

The logic can be separated into several key components:

* Communication with the device managers,

* Communication with the HMI,

* The startup method which reads the configuration and starts all the necessary threads,

* The device manager.

h3. The startup method

The startup method is run when the logic program first starts and is responsible for setting up all the threads according to the configuration XML file. It starts a "Device manager <--> The Logic" thread for each measuring device found in the configuration file. Then it should start the "HMI <--> The Logic" thread. 

After the initialization is complete this function waits for termination signal (via HMI). When the termination signal is received it should stop all the "Device manager <--> The Logic" threads, leaving only one communication channel open: The "HMI <--> The Logic" thread. The function then waits for the resume signal (from HMI). When the resume signal is received, the configuration file is used to restart the "Device manager <--> The Logic" communication.

It should also be noted that the configuration file may change (due to human interaction via HMI). When that happens the "HMI <--> The Logic" thread signals The startup method which in response rechecks the file for changes and acts accordingly.

h3. Communication with the HMI

Communication with the HMI runs in its own thread (see *The startup method*). It consists of a blocking socket server that waits for incoming message from the HMI. When the connection is established a new thread is started to deal with the request and the main thread starts waiting for another connection.

This part of the Logic interacts with The startup method for signaling it the termination/resume signal. It is also interacting with the "Device manager <--> The Logic" threads for generating responses to incoming requests from HMI.

h3. Communication with the device managers

Communication with the device managers runs in its own threads, one for each measuring device (see *The startup method*). The communication with the device manager is twofold (see *The logic <--> device manager message*). This thread waits for the device manager to signal a change in its status variable. The change is then logged (via Syslog). The new value is evaluated and any necessary action program is run. This continues until the termination signal (from "The startup method") is received.

The other assignment of this thread is to create a response for the HMI. When the request is received the "HMI <--> The Logic" reads the last value read from the thread and returns it to HMI.

*Note:* It was previously discussed that a new value should be requested from the device manager for the response to the HMI. This is still an option, however the logic software is becoming rather complex. If the device managers check their value often enough and signal for every change then the value should be up to date thus making another communication channel redundant.

h3. Device manager

The device manager is a program that can read from a measuring device. It reads the value periodically and signals The Logic on every change.