top/int.tex

   1 \documentclass[../thesis.tex]{subfiles}
   2
   3 \input{subfilepreamble}
   4
   5 \setcounter{chapter}{5}
   6
   7 \begin{document}
   8 \input{subfileprefix}
   9 \chapter{Integration with \texorpdfstring{\gls{ITASK}}{iTask}}%
  10 \label{chp:integration_with_itask}
  11 \begin{chapterabstract}
  12         \noindent This chapter shows the integration of \gls{MTASK} with \gls{ITASK} by showing:
  13         \begin{itemize}
  14                 \item an architectural overview \gls{MTASK} applications;
  15                 \item on the interface for connecting devices;
  16                 \item the interface for lifting \gls{MTASK} tasks to \gls{ITASK} tasks;
  17                 \item a interface for lifting \gls{ITASK} \glspl{SDS} to \gls{MTASK} \glspl{SDS};
  18                 \item and finishes with non-trivial home automation example application using all integration mechanisms;
  19         \end{itemize}
  20 \end{chapterabstract}
  21
  22 The \gls{MTASK} language is a multi-view \gls{DSL}, i.e.\ there are multiple interpretations possible for a single \gls{MTASK} term.
  23 Using the byte code compiler (\cleaninline{BCInterpret}) \gls{DSL} interpretation, \gls{MTASK} tasks can be fully integrated in \gls{ITASK}.
  24 They are executed as if they are regular \gls{ITASK} tasks and they communicate may access \glspl{SDS} from \gls{ITASK} as well.
  25 \Gls{MTASK} devices contain a domain-specific \gls{OS} and are little \gls{TOP} engines in their own respect, being able to execute tasks.
  26 \Cref{fig:mtask_integration} shows the architectural layout of a typical \gls{IOT} system created with \gls{ITASK} and \gls{MTASK}.
  27 The entire system is written as a single \gls{CLEAN} specification where multiple tasks are executed at the same time.
  28 Tasks can access \glspl{SDS} according to many-to-many communication and multiple clients can work on the same task.
  29 Devices are integrated into the system using the \cleaninline{withDevice} function (see \cref{sec:withdevice}).
  30 Using \cleaninline{liftmTask}, \gls{MTASK} tasks are lifted to a device (see \cref{sec:liftmtask}).
  31 \Gls{ITASK} \glspl{SDS} are lifted to the \gls{MTASK} device using \cleaninline{liftsds} (see \cref{sec:liftsds}).
  32
  33 \begin{figure}[ht]
  34         \centering
  35         \includestandalone{mtask_integration}
  36         \caption{\Gls{MTASK}'s integration with \gls{ITASK}.}%
  37         \label{fig:mtask_integration}
  38 \end{figure}
  39
  40 \section{Connecting edge devices}\label{sec:withdevice}
  41 When interpreted by the byte code compiler view, an \gls{MTASK} task produces a compiler.
  42 This compiler is exceuted at run time so that the resulting byte code can be sent to an edge device.
  43 All communication with this device happens through a so-called \emph{channels} \gls{SDS}.
  44 The channels contain three fields, a queue of messages that are received, a queue of messages to send and a stop flag.
  45 Every communication method that implements the \cleaninline{channelSync} class can provide the communication with an \gls{MTASK} device.
  46 As of now, serial port communication, direct \gls{TCP} communication and \gls{MQTT} over \gls{TCP} are supported as communication providers (see \cref{lst:connection_types}).
  47 The \cleaninline{withDevice} function transforms such a communication provider and a task that does something with this device to an \gls{ITASK} task.
  48 Internally, the task sets up the communication, exchanges specifications with the device, executes the inner task while handling errors, and finally cleans up after closing.
  49 \Cref{lst:mtask_device} shows the types and interface to connecting devices.
  50
  51 \begin{lstClean}[label={lst:mtask_device},caption={Device communication interface in \gls{MTASK}.}]
  52 :: MTDevice //abstract
  53 :: Channels :== ([MTMessageFro], [MTMessageTo], Bool)
  54
  55 class channelSync a :: a (Shared sds Channels) -> Task () | RWShared sds
  56
  57 withDevice :: a (MTDevice -> Task b)
  58         -> Task b | iTask b & channelSync, iTask a
  59 \end{lstClean}
  60
  61 \subsection{Implementation}
  62 \Cref{lst:pseudo_withdevice} shows a pseudocode implementation of the \cleaninline{withDevice} function.
  63 The \cleaninline{MTDevice} abstract type is internally represented as three \gls{ITASK} \gls{SDS} that contain all the current information about the tasks.
  64 The first \gls{SDS} is the information about the \gls{RTS} of the device, i.e.\ metadata on the tasks that are executing, the hardware specification and capabilities, and a list of fresh task identifiers.
  65 The second \gls{SDS} is a map storing downstream \gls{SDS} updates.
  66 When a lifted \gls{SDS} is updated on the device, a message is sent to the server.
  67 This message is initially queued in the map to allow for asynchronous handling of multiple updates.
  68 Finally, the \cleaninline{MTDevices} type contains the communication channels.
  69
  70 The \cleaninline{withDevice} task itself first constructs the \glspl{SDS} using the \gls{ITASK} function \cleaninline{withShared} to create anonymous local \glspl{SDS}.
  71 Then, it performs the following four tasks in parallel to monitor the edge device.
  72 \begin{enumerate}
  73         \item It synchronises the channels using the \cleaninline{channelSync} overloaded function.
  74                 Errors that occur here are converted to the proper \gls{MTASK} exception.
  75         \item Watches the channels for the shutdown flag.
  76                 If the connection is lost with the device unexpectedly, an \gls{MTASK} exception is thrown.
  77         \item Watches the channels for messages and processes them accordingly by changing the device information \gls{SDS} or adding the lifted \gls{SDS} updates to the corresponding \gls{SDS} update queue.
  78         \item Sends a request for a specification. Once the specification is received, the device task is run.
  79                 The task value of this device task is then used as the task value of the \cleaninline{withDevice} task.
  80 \end{enumerate}
  81
  82 \begin{lstClean}[caption={Pseudocode for the \texttt{widthDevice} function},label={lst:pseudo_withdevice}]
  83 withDevice spec deviceTask =
  84         withShared newMap \sdsupdates->
  85         withShared ([], [MTTSpecRequest], False) \channels->
  86         withShared default \dev->parallel
  87                 [ channelSync spec channels
  88                 , watchForShutdown channels
  89                 , watchChannelMessages dev channels
  90                 , waitForSpecification
  91                         >>| deviceTask
  92                         >>* [ifStable: issueShutdown]
  93                 ]
  94 \end{lstClean}
  95
  96 If at any stage an unrecoverable device error occurs, an \gls{ITASK} exception is thrown on the \cleaninline{withDevice} task.
  97 This exception can be caught in order to device some kind of fail-safe mechanism.
  98 For example, when a device fails, the tasks can be sent to another device as can be seen in \cref{lst:failover}.
  99 This function executes an \gls{MTASK} task on a pool of devices.
 100 If an error occurs during execution, the next device in the pool is tried until the pool is exhausted
 101
 102 \begin{lstClean}[caption={An \gls{MTASK} failover combinator.},label={lst:failover}]
 103 failover :: [TCPSettings] (Main (MTask BCInterpret a)) -> Task a
 104 failover []     _     = throw "Exhausted device pool"
 105 failover [d:ds] mtask = try (withDevice d (liftmTask mtask)) except
 106 where except MTEUnexpectedDisconnect = failover ds mtask
 107           except _                       = throw e
 108 \end{lstClean}
 109
 110 \section{Lifting \texorpdfstring{\gls{MTASK}}{mTask} tasks}\label{sec:liftmtask}
 111 Once the connection with the device is established, \gls{MTASK} tasks can be lifted to \gls{MTASK} tasks using the \cleaninline{liftmTask} family of functions (see \cref{lst:liftmtask}).
 112 Given an \gls{MTASK} task in the \cleaninline{BCInterpret} view and a device obtained from \cleaninline{withDevice}, an \gls{ITASK} task is returned.
 113 This \gls{ITASK} task tethers the \gls{MTASK} task that is executed on the microcontroller.
 114 Hence, when for example observing the task value, the actual task value from the microcontroller is observed.
 115
 116 \begin{lstClean}[label={lst:liftmtask},caption={The interface for lifting \gls{MTASK} tasks to \gls{ITASK} tasks.}]
 117 liftmTask :: (Main (MTask BCInterpret a)) MTDevice -> Task a | iTask a
 118 \end{lstClean}
 119
 120 \subsection{Implementation}
 121 \Cref{lst:liftmTask_pseudo} shows the pseudocode for the \cleaninline{liftmTask} implementation
 122 The first argument is the task and the second argument is the device which is just an \gls{ADT} containing the \glspl{SDS} referring to the device information, the \gls{SDS} update queue, and the channels.
 123 First a fresh identifier for the task is generated using the device state.
 124 With this identifier, the cleanup hook can be installed.
 125 This is done to assure the task is removed from the edge device if the \gls{ITASK} task coordinating it is destroyed.
 126 Tasks can be destroyed when for example a task executed in parallel and the parallel combinator terminates or when the condition to step holds in a sequential task combination.
 127 Then the \gls{MTASK} compiler is invoked, its only argument besides the task is a function doing something with the results of the compilation, i.e.\ the lifted \glspl{SDS} and the messages containing the compiled and serialised task.
 128 With the result of the compilation, the task can be executed.
 129 First the messages are put in the channels, sending them to the device.
 130 Then, in parallel:
 131 \begin{enumerate*}
 132         \item the value is watched by looking in the device state \gls{SDS}, this task also determines the task value of the whole task
 133         \item the downstream \glspl{SDS} are monitored, i.e.\ the \cleaninline{sdsupdates} \gls{SDS} is monitored and updates from the device are applied to the associated \gls{ITASK} \gls{SDS}
 134         \item the upstroam \glspl{SDS} are monitored by spawning tasks that watch these \glspl{SDS}, if one is updated, the novel value is sent to the edge device.
 135 \end{enumerate*}
 136
 137 \begin{lstClean}[label={lst:liftmTask_pseudo},caption={Pseudocode implementation for \texttt{liftmTask}.}]
 138 liftmTask task (MTDevice dev sdsupdates channels)
 139         = freshTaskId dev
 140         >>= \tid->withCleanupHook (sendmessage [MTTTaskDel tid] channels) (
 141                 compile task \mrefs msgs->
 142                         sendMessage msgs channels
 143                         >>| waitForReturnAndValue tid dev
 144                         -|| watchSharesDownstream mrefs tid sdsupdates
 145                         -|| watchSharesUpstream mrefs channels tid)
 146 \end{lstClean}
 147
 148 \todo{dis\-cuss pre\-loading}
 149
 150 \section{Lifting \texorpdfstring{\gls{ITASK}}{iTask} \texorpdfstring{\glsxtrlongpl{SDS}}{shared data sources}}\label{sec:liftsds}
 151 Lifting \gls{ITASK} \glspl{SDS} to \gls{MTASK} \glspl{SDS} is something that mostly happens at the compiler level using the \cleaninline{liftsds} function (see \cref{lst:mtask_itasksds}).
 152 \Glspl{SDS} in \gls{MTASK} must always have an initial value.
 153 For regular \gls{SDS} this value is given in the source code, for lifted \gls{ITASK} \glspl{SDS} this value is obtained by reading the values once just before sending the task to the edge device.
 154 On the device itself, there is just one difference between lifted \glspl{SDS} and regular \glspl{SDS}: after changing \pgls{SDS}, a message is sent to the server containing this new value.
 155 The \cleaninline{withDevice} task (see \cref{sec:withdevice}) receives and processes this message by writing to the \gls{ITASK} \gls{SDS}.
 156 Tasks watching this \gls{SDS} get notified then through the normal notification mechanism of \gls{ITASK}.
 157
 158 \begin{lstClean}[label={lst:mtask_itasksds},caption={Lifted \gls{ITASK} \glspl{SDS} in \gls{MTASK}.}]
 159 class liftsds v where
 160         liftsds :: ((v (Sds t)) -> In (Shared sds t) (Main (MTask v u)))
 161                 -> Main (MTask v u) | RWShared sds
 162 \end{lstClean}
 163
 164 As an example, \cref{lst:mtask_liftsds_ex} shows a lightswitch function producing an \imtask{} task.
 165 Given an \cleaninline{MTDevice} type, a device handle, an \gls{ITASK} \gls{SDS} of the type boolean is created.
 166 This boolean represents the state of the light.
 167 The \gls{MTASK} task uses this \gls{SDS} to turn on or off the light.
 168 An \gls{ITASK} task that runs in parallel allows interactive updating of this state.
 169
 170 \todo{dit voor\-beeld aan\-hou\-den of al\-leen die gro\-te ge\-brui\-ken}
 171 \begin{lstClean}[label={lst:mtask_liftsds_ex},caption={Interactive light switch program.}]
 172 lightswitch dev  =
 173         withShared False \sh->
 174                     liftmTask (mtask sh) dev
 175                 -|| updateSharedInformation [] sh
 176                 <<@ Hint "Light switch"
 177 where
 178         mtask sh =
 179                 declarePin D13 PMOutput \d13->
 180                 liftsds \ls=sh
 181                 In fun \f=(\st->
 182                              getSds ls
 183                         >>*. [IfValue ((!=.)st) (\v->writeD d13 v)]
 184                         >>|. f (Not st))
 185                 In {main=f true}
 186 \end{lstClean}
 187
 188 \subsection{Implementation}
 189 The compilation of the code and the serialisation of the data throws away all typing information.
 190 \Glspl{SDS} are stored in the compiler state as a map from identifiers to either an initial value or an \cleaninline{MTLens}.
 191 The \cleaninline{MTLens} is a type synonym for a \gls{SDS} that represents the typeless serialised value of the underlying \gls{SDS}.
 192 This is done so that the \cleaninline{withDevice} task can write the received \gls{SDS} updates to the according \gls{SDS} independently.
 193 \Gls{ITASK}'s notification mechanism then takes care of the rest.
 194 Such a \gls{SDS} is created by using the \cleaninline{mapReadWriteError} which, given a pair of read and write functions with error handling, produces a \gls{SDS} with the lens embedded.
 195 The read function transforms, the function that converts a typed value to a typeless serialised value, just applies the serialisation.
 196 The write function, the function that, given the new serialised value and the old typed value, produces a new typed value.
 197 It tries to decode the serialised value, if that succeeds, it is written to the underlying \gls{SDS}, an error is thrown otherwise.
 198 \Cref{lst:mtask_itasksds_lens} provides the implementation for this:
 199
 200 % VimTeX: SynIgnore on
 201 \begin{lstClean}[label={lst:mtask_itasksds_lens},caption={Lens applied to lifted \gls{ITASK} \glspl{SDS} in \gls{MTASK}.}]
 202 lens :: (Shared sds a) -> MTLens | type a & RWShared sds
 203 lens sds = mapReadWriteError
 204         ( \r->   Ok (fromString (toByteCode{|*|} r)
 205         , \w r-> ?Just <$> iTasksDecode (toString w)
 206         ) ?None sds
 207 \end{lstClean}
 208 % VimTeX: SynIgnore off
 209
 210 \Cref{lst:mtask_itasksds_lift} shows the code for the implementation of \cleaninline{liftsds} that uses the \cleaninline{lens} function shown earlier.
 211 First, the \gls{SDS} to be lifted is extracted from the expression by bootstrapping the fixed point with a dummy value.
 212 This is safe because the expression on the right-hand side of the \cleaninline{In} is never evaluated.
 213 Then, using \cleaninline{addSdsIfNotExist}, the identifier for this particular \gls{SDS} is either retrieved from the compiler state or generated freshly.
 214 This identifier is then used to provide a reference to the \cleaninline{def} definition to evaluate the main expression.
 215
 216 % VimTeX: SynIgnore on
 217 \begin{lstClean}[label={lst:mtask_itasksds_lift},caption={Lens applied to lifted \gls{ITASK} \glspl{SDS} in \gls{MTASK}.}]
 218         liftsds def = {main =
 219                         let (t In _) = def (abort "liftsds: expression too strict")
 220                         in addSdsIfNotExist (Right $ lens t)
 221                                 >>= \sdsi->let (_ In e) = def (pure (Sds sdsi)) in e.main
 222                 }\end{lstClean}
 223 % VimTeX: SynIgnore off
 224
 225 \section{Home automation}
 226 This section presents a interactive home automation program (\Cref{lst:example_home_automation}) to illustrate \gls{MTASK}'s integration with \gls{ITASK}.
 227 It consists of a web interface for the user to control which tasks may be executed on either of two connected devices: an \gls{ARDUINO} UNO, connected via a serial port; and an ESP8266 based prototyping board called NodeMCU, connected via \gls{TCP} over WiFi.
 228
 229 \Crefrange{lst:example:spec1}{lst:example:spec2} show the specification for the devices.
 230 The UNO is connected via serial using the unix filepath \path{/dev/ttyACM0} and the default serial port settings.
 231 The NodeMCU is connected via WiFi and hence the \cleaninline{TCPSettings} record is used.
 232 Both types have \cleaninline{channelSync} instances.
 233
 234 The code consists of an \gls{ITASK} part and several \gls{MTASK} parts.
 235 \Crefrange{lst:example:task1}{lst:example:task2} containing the \gls{ITASK} task that coordinates the \gls{IOT} application.
 236 It first connects the devices (\crefrange{lst:example:conn1}{lst:example:conn2}) followed by launching a \cleaninline{parallel} task, visualized as a tabbed window, and a shutdown button to terminate the program (\crefrange{lst:example:par1}{lst:example:par2}).
 237 This parallel task is the controller of the tasks that run on the edge devices.
 238 It contains one task that allows adding new tasks (using \cleaninline{appendTask}) and all other tasks in the process list will be \gls{MTASK} tasks once they are added by the user.
 239 The controller task, \cleaninline{chooseTask} as shown in \crefrange{lst:example:ct1}{lst:example:ct2}, allows the user to pick a task, sending it to the specified device.
 240 Tasks are picked by index from the \cleaninline{tasks} list (\crefrange{lst:example:tasks1}{lst:example:tasks2}) using \cleaninline{enterChoice}.
 241 The interface that is generated for this can be seen in \cref{fig:example_screenshots1}.
 242 After selecting the task, a device is selected (see \cref{fig:example_screenshots2,lst:example:selectdev}).
 243 When both a task and a device is selected, an \gls{ITASK} task is added to the process list using \cleaninline{appendTask}.
 244 Using the helper function \cleaninline{mkTask}, the actual task is selected from the \cleaninline{tasks} list and executed by providing the device argument.
 245 For example, when selecting the \cleaninline{temperature} task, the current temperature is shown to the user (\cref{fig:example_screenshots3}).
 246 This task just sends a simple temperature monitoring task to the device using \cleaninline{liftmTask} and provides a view on its task value using the \cleaninline{>\&>}\footnotemark{} \gls{ITASK} combinator.
 247 \footnotetext{\cleaninline{(>\&>) infixl 1 :: (Task a) ((SDSLens () (? a) ()) -> Task b) -> Task b \| iTask a \& iTask b}}
 248 The light switch task at \crefrange{lst:example:ls1}{lst:example:ls2} is a task that has bidirectional interaction using the definition of \cleaninline{lightswitch} shown in \cref{lst:mtask_liftsds_ex}.
 249 Using \cleaninline{liftsds}, the status of the light switch is synchronised with the user.
 250 The task on the edge device continuously monitors the value of the lifted \gls{SDS}.
 251 If it is different from the current state, the new value is written to the digital \gls{GPIO} pin 13 and the monitoring function is recursively called.
 252
 253 \begin{figure}[ht]
 254         \centering
 255         \begin{subfigure}[b]{.3\linewidth}
 256                 \includegraphics[width=\linewidth]{home_auto1}
 257                 \caption{Select task.}%
 258                 \label{fig:example_screenshots1}
 259         \end{subfigure}
 260         \begin{subfigure}[b]{.3\linewidth}
 261                 \includegraphics[width=\linewidth]{home_auto2}
 262                 \caption{Select device.}%
 263                 \label{fig:example_screenshots2}
 264         \end{subfigure}
 265         \begin{subfigure}[b]{.3\linewidth}
 266                 \includegraphics[width=\linewidth]{home_auto3}
 267                 \caption{View result.}%
 268                 \label{fig:example_screenshots3}
 269         \end{subfigure}
 270         \caption{Screenshots of the home automation example program in action.}%
 271         \label{fig:example_screenshots}
 272 \end{figure}
 273
 274 \begin{figure}
 275         \cleaninputlisting[firstline=12,lastline=50,numbers=left,belowskip=0pt]{lst/example.icl}
 276         \begin{lstClean}[numbers=left,firstnumber=40,aboveskip=0pt,caption={An example of a home automation program.},label={lst:example_home_automation}]
 277         , ...][+\label{lst:example:tasks2}+]\end{lstClean}
 278 \end{figure}
 279
 280 \section{Conclusion}
 281 \Gls{MTASK} edge devices run little \gls{TOP} engines of their own.
 282 Using only a couple of \gls{ITASK} functions, \gls{MTASK} tasks can be integrated in \gls{ITASK} seamlessly.
 283 Devices, using any supported type of connection, are integrated in \gls{ITASK} using the \cleaninline{withDevice} function.
 284 Once connected, \gls{MTASK} tasks can be sent to the device for execution using \cleaninline{liftmTask}, lifting them to full-fledged \gls{ITASK} tasks.
 285 Furthermore, the \gls{MTASK} tasks can interact with \gls{ITASK} \glspl{SDS} using the \cleaninline{liftsds} construct.
 286 This together allows entire \gls{IOT} systems to be programmed from a single source.
 287
 288 \input{subfilepostamble}
 289 \end{document}