and send it to the server so that the server knows what the client is capable
of. The exact specification is listed in Listing~\ref{lst:devicespec}
-\begin{lstlisting}[language=Clean,label={lst:devicespec},
+\begin{lstlisting}[label={lst:devicespec},
caption={Device specification for \glspl{mTask}}]
:: MTaskDeviceSpec =
{haveLed :: Bool
}
\end{lstlisting}
-\section{Communication}
-The communication to and fro a device runs via a single \gls{SDS}. Every
-device has a specific resource that is used to connect to the device. The
-current system supports connecting devices via a serial connection and via a
-\gls{TCP} connection. Every device has the type \CI{MTaskDevice} and which
-is listed in Listing~\ref{lst:mtaskdevice}. When a device is added, a background
-\gls{Task} is started that runs the \CI{synFun}. The \CI{synFun} is the task that
-synchronizes the channel \gls{SDS} with the actual device. For the \gls{TCP}
-device this is a simple \CI{tcpconnect}. The \CI{TaskId} of the background task
-is saved to be able to stop the task in the future. When the task is unable to
-connect it will set the \CI{deviceError} field to notify the user.
-\todo{netter maken}
-
-\begin{lstlisting}[language=Clean,caption={Device type},label={lst:mtaskdevice}]
+\section{Device Storage}
+All devices available in the system are stored in a big \gls{SDS} that contains
+a list of \CI{MTaskDevice}s. The exact specification is listed in
+Listing~\ref{lst:mtaskdevice} with the accompanying classes and types.
+
+The \CI{deviceResource} component of the record must implement the
+\CI{MTaskDuplex} interface that provides a function that launches a task used
+for synchronizing the channels. The \CI{deviceTask} stores the \gls{Task}-id
+for this \gls{Task} when active so that it can be checked upon. This top-level
+task has the duty to report set the \CI{deviceError} field whenever an error
+occurs. All communication goes via these channels. If the system wants to send
+a message to the device it just puts it in the channels. Messages sent from the
+client to the server are also placed in there. In the case of the \gls{TCP}
+device type the \gls{Task} is just a simple wrapper around the existing
+\CI{tcpconnect} function in \gls{iTasks}. In case of the serial device type it
+uses the newly developed serial port library of \gls{Clean}\footnote{\url{%
+https://gitlab.science.ru.nl/mlubbers/CleanSerial}}.
+
+Besides all the communication information the record also keeps track of the
+\glspl{Task} currently on the device and the according \glspl{SDS}. Finally it
+stores the specification of the device that is received when connecting.
+All of this is listed in Listing~\ref{lst:mtaskdevice}. The definitions of the
+message format are explained in the following section.
+
+\begin{lstlisting}[caption={Device type},label={lst:mtaskdevice}]
+deviceStore :: Shared [MTaskDevice]
+
:: Channels :== ([MTaskMSGRecv], [MTaskMSGSend], Bool)
:: MTaskResource
= TCPDevice TCPSettings
, deviceShares :: [MTaskShare]
}
+channels :: MTaskDevice -> Shared Channels
+
class MTaskDuplex a where
synFun :: a (Shared Channels) -> Task ()
\end{lstlisting}
+
+\section{Communication}
+All \gls{mTask} messages are encoded following the specification given in
+Appendix~\ref{app:communication-protocol}. Available messages are:
+\begin{lstlisting}[caption={Available messages}]
+:: MTaskMSGRecv
+ = MTTaskAck Int Int | MTTaskDelAck Int
+ | MTSDSAck Int | MTSDSDelAck Int
+ | MTPub Int BCValue | MTMessage String
+ | MTDevSpec MTaskDeviceSpec | MTEmpty
+
+:: MTaskMSGSend
+ = MTTask MTaskInterval String | MTTaskDel Int
+ | MTShutdown | MTSds Int BCValue
+ | MTUpd Int BCValue | MTSpec
+
+:: MTaskInterval = OneShot | OnInterval Int | OnInterrupt Int
+\end{lstlisting}
+
+\subsection{Add a device}
+A device can be added by filling in the \CI{MTaskDevice} record as much as
+possible and running the \CI{connectDevice} function. This function grabs the
+channels, starts the synchronization \gls{Task}, makes sure the errors are
+handled when needed and runs a processing function in parallel to react on the
+incoming messages. Moreover, it sends a specification request to the device in
+question to determine the details of the device and updates the record to
+contain the top-level \gls{Task}-id. All the device functionality heavily
+depends on the \CI{withDevices} function that applies a function a device in
+the \gls{SDS} when they are equal. Device equality is defined as equality on
+their channels. This allows you to give an old device record to the function
+and still update the latest instance. Listing~\ref{lst:connectDevice} shows the
+connection function.
+
+\begin{lstlisting}[label={lst:connectDevice},%
+ caption={Connect a device}]
+withDevices :: MTaskDevice (MTaskDevice -> MTaskDevice) -> Task [MTaskDevice]
+
+connectDevice :: (MTaskDevice (Shared Channels) -> Task ()) MTaskDevice -> Task Channels
+connectDevice procFun device = let ch = channels device
+ in appendTopLevelTask 'DM'.newMap True
+ (procFun device ch -||- catchAll (getSynFun d.deviceData ch) errHdl)
+ >>= \tid->withDevices device (\d->{d&deviceTask=Just tid,deviceError=Nothing})
+ >>| upd (\(r,s,ss)->(r,s++[MTSpec],ss)) ch
+ where
+ errHdl e = withDevices device (\d->{d & deviceTask=Nothing, deviceError=Just e}) @! ()
+\end{lstlisting}
+
+Figure~\ref{fig:handshake} shows the connection diagram. The client responds to
+the server with their device specification. This is detected by the processing
+function and the record is updated accordingly.
+
+\begin{figure}[H]
+ \begin{sequencediagram}
+ \newthread{s}{Server}
+ \newinst[4]{c}{Client}
+ \begin{call}{s}{MTSpec}{c}{MTDevSpec}
+ \end{call}
+ \end{sequencediagram}
+ \caption{Connect a device}\label{fig:handshake}
+\end{figure}
+
+\subsection{\glspl{Task}}
+\subsection{\glspl{SDS}}
+\todo{Connectie, hoe gaat dat in zijn werk}
repositories / msc-thesis1617.git / blobdiff