arch.communication.tex

   1 The communication from the server to the client and vice versa is just a
   2 character stream containing encoded \gls{mTask} messages. The \CI{synFun}
   3 belonging to the device is responsible for sending the content in the left
   4 channel and putting received messages in the right channel. Moreover, the
   5 boolean value should be set to \CI{True} when the connection is terminated. The
   6 specific encoding of the messages is visible in
   7 Appendix~\ref{app:communication-protocol}. The type holding the messages is
   8 shown in Listing~\ref{lst:avmsg}. Detailed explanation about the message types
   9 and according actions will be given in the following subsections.
  10
  11 \begin{lstlisting}[label={lst:avmsg},caption={Available messages}]
  12 :: MTaskId :== Int
  13 :: MSDSId :== Int
  14 :: MTaskFreeBytes :== Int
  15 :: MTaskMSGRecv
  16         = MTTaskAck MTaskId MTaskFreeBytes | MTTaskDelAck MTaskId
  17         | MTSDSAck MSDSId                  | MTSDSDelAck MSDSId
  18         | MTPub MSDSId BCValue             | MTMessage String
  19         | MTDevSpec MTaskDeviceSpec        | MTEmpty
  20
  21 :: MTaskMSGSend
  22         = MTTask MTaskInterval String | MTTaskDel MTaskId
  23         | MTShutdown                  | MTSds MSDSId BCValue
  24         | MTUpd MSDSId BCValue        | MTSpec
  25
  26 :: MTaskInterval = OneShot | OnInterval Int | OnInterrupt Int
  27 \end{lstlisting}
  28
  29 \subsection{Add a device}
  30 A device can be added by filling in the \CI{MTaskDevice} record as much as
  31 possible and running the \CI{connectDevice} function. This function grabs the
  32 channels, starts the synchronization \gls{Task} (\CI{synFun}), makes sure the
  33 errors are handled when needed and runs a processing function in parallel to
  34 react on the incoming messages. Moreover, it sends a specification request to
  35 the device in question to determine the details of the device and updates the
  36 record to contain the top-level \gls{Task}-id. All device functionality
  37 heavily depends on the specific \CI{deviceShare} function that generates an
  38 \gls{SDS} for a specific device. This allows giving an old device record to the
  39 function and still update the latest instance. Listing~\ref{lst:connectDevice}
  40 shows the connection function.
  41
  42 \begin{lstlisting}[label={lst:connectDevice},%
  43         caption={Connect a device}]
  44 connectDevice :: (MTaskDevice (Shared Channels) -> Task ()) MTaskDevice -> Task Channels
  45 connectDevice procFun device = set ([], [], False) ch
  46                 >>| appendTopLevelTask 'DM'.newMap True
  47                 (       procFun device ch -||- catchAll (getSynFun device.deviceData ch) errHdl)
  48                 >>= \tid->upd (\d->{d&deviceTask=Just tid,deviceError=Nothing}) (deviceShare device)
  49                 >>| upd (\(r,s,ss)->(r,s++[MTSpec],ss)) ch
  50 where
  51         errHdl e = upd (\d->{d & deviceTask=Nothing, deviceError=Just e}) (deviceShare device) @! ()
  52         ch = channels device
  53 \end{lstlisting}
  54
  55 Figure~\ref{fig:handshake} shows the connection diagram. The client responds to
  56 the server with their device specification. This is detected by the processing
  57 function and the record is updated accordingly.
  58
  59 \begin{figure}[H]
  60         \centering
  61         \begin{sequencediagram}
  62                 \newthread{s}{Server}
  63                 \newinst[4]{c}{Client}
  64                 \begin{call}{s}{MTSpec}{c}{MTDevSpec}
  65                 \end{call}
  66         \end{sequencediagram}
  67         \caption{Connect a device}\label{fig:handshake}
  68 \end{figure}
  69
  70 \subsection{\glspl{Task} \& \glspl{SDS}}
  71 When a \gls{Task} is sent to the device it is added to the device record
  72 without an identifier. The actual identifier is added to the record when the
  73 acknowledgement of the \gls{Task} by the device is received. The connection
  74 diagram is shown in Figure~\ref{fig:tasksend}.
  75
  76 \begin{figure}[H]
  77         \centering
  78         \begin{sequencediagram}
  79                 \newthread{s}{Server}
  80                 \newinst[4]{c}{Client}
  81                 \begin{call}{s}{MTSDS}{c}{MTSDSAck}
  82                 \end{call}
  83                 \begin{call}{s}{MTTask}{c}{MTTaskAck}
  84                 \end{call}
  85         \end{sequencediagram}
  86         \caption{Sending a \gls{Task} to a device}\label{fig:tasksend}
  87 \end{figure}
  88
  89 The function for sending a \gls{Task} to the device is shown in
  90 Listing~\ref{lst:sendtask}. First the \gls{Task} is compiled into messages. The
  91 details of the compilation process are given in Section~\ref{sec:compiler}.
  92 The new \glspl{SDS} that were generated during compilation are merged with the
  93 existing device's \glspl{SDS}. Furthermore the messages are placed in the
  94 channel \gls{SDS} of the device. This will result in sending the actual \gls{SDS}
  95 specification and \gls{Task} specifications to the device. A \gls{Task} record
  96 is created with the identifier $-1$ to denote a \gls{Task} not yet
  97 acknowledged. Finally the device itself is updated with the new state and with
  98 the new \gls{Task}.  After waiting for the acknowledgement the device is
  99 updated again and the \gls{Task} returns.
 100
 101 \begin{lstlisting}[label={lst:sendtask},%
 102         caption={Sending a \gls{Task} to a device}]
 103 makeTask :: String Int -> Task MTaskTask
 104 makeTask name ident = get currentDateTime @ \dt->{MTaskTask | name=name, ident=ident, dateAdded=dt}
 105
 106 makeShare :: String Int BCValue -> MTaskShare
 107 makeShare withTask identifier value = {MTaskShare | withTask=[withTask], identifier=identifier, value=value}
 108
 109 sendTaskToDevice :: String (Main (ByteCode a Stmt)) (MTaskDevice, MTaskInterval) -> Task MTaskTask
 110 sendTaskToDevice wta mTask (device, timeout)
 111 # (msgs, newState=:{sdss}) = toMessages timeout mTask device.deviceState
 112 # shares = [makeShare wta "" sdsi sdsval\\{sdsi,sdsval}<-sdss, (MTSds sdsi` _)<-msgs | sdsi == sdsi`]
 113 = updateShares device ((++) shares)
 114         >>| sendMessages msgs device
 115         >>| makeTask wta -1
 116         >>= \t->upd (addTaskUpState newState t) (deviceShare device)
 117         >>| wait "Waiting for task to be acked" (taskAcked t) (deviceShare device)
 118         >>| treturn t
 119 where
 120         addTaskUpState :: BCState MTaskTask MTaskDevice -> MTaskDevice
 121         addTaskUpState st task device = {MTaskDevice | device & deviceState=st, deviceTasks=[task:device.deviceTasks]}
 122         taskAcked t d = maybe True (\t->t.ident <> -1) $ find (eq t) d.deviceTasks
 123         eq t1 t2 = t1.dateAdded == t2.dateAdded && t1.MTaskTask.name == t2.MTaskTask.name
 124 \end{lstlisting}
 125
 126 \subsection{Miscellaneous Messages}
 127 One special type of message is available which is sent to the device only when
 128 it needs to reboot. When the server wants to stop the bond with the device it
 129 sends the \CI{MTShutdown} message. The device will then clear its memory, thus
 130 losing all the \glspl{SDS} and \glspl{Task} that were stored and reset itself.
 131 Shortly after the shutdown message a new server can connect to the device
 132 because the device is back in listening mode.
 133
 134 \subsection{Integration}
 135 When the system starts up, the devices from the previous execution still
 136 residing in the \gls{SDS} must be cleaned up. It might be the case that they
 137 contain \glspl{Task}, \glspl{SDS} or errors that are no longer applicable in
 138 this run. A user or programmer can later choose to reconnect to some devices.
 139
 140 \begin{lstlisting}[caption={Starting up the devices},%
 141         label={lst:startupdevs}]
 142 startupDevices :: Task [MTaskDevice]
 143 startupDevices = upd (map reset) deviceStoreNP
 144         where reset d = {d & deviceTask=Nothing, deviceTasks=[], deviceError=Nothing}
 145 \end{lstlisting}
 146
 147 The system's management is done through the interface of a single \gls{Task}
 148 called \CI{mTaskManager}. To manage the system, a couple of different
 149 functionalities are necessary and are launched. An image of the management
 150 interface is shown in Figure~\ref{lst:manage}. The left sidebar of the
 151 interface shows the list of example \glspl{Task} that are present in the
 152 system. When clicking a \gls{Task}, a dialog opens in which a device can be
 153 selected to send the \gls{Task} to. The dialog might contain user specified
 154 variables. All example \gls{mTask}-\glspl{Task} are of the type \CI{Task (Main
 155 (ByteCode () Stmt))} and can thus ask for user input first if needed for
 156 parameterized \gls{mTask}-\glspl{Task}. The bottom panel shows the device
 157 information. In this panel, the devices can be created and modified. Moreover,
 158 this panel allows the user to reconnect with a device after a restart of the
 159 server application.
 160
 161 \begin{figure}[H]
 162         \centering
 163         \includegraphics[width=\linewidth]{manage}
 164         \caption{The device management interface}\label{lst:manage}
 165 \end{figure}