Commits

Trent Houliston committed 4d1de22

Editing the proposed architecture section

Comments (0)

Files changed (1)

Requirements Document.tex

 	}
 }
 
+\newglossaryentry{reaction}
+{
+	name=Reaction,
+	description={
+		is the reaction
+	}
+}
+
 \newglossaryentry{nubots}
 {
 	name=NUBots,
 				\label{fig:HighLevelProposedArchitecture}
 			\end{figure}
 
-			As you can see in Figure~\ref{fig:HighLevelProposedArchitecture} on page~\pageref{fig:HighLevelProposedArchitecture} the central authority of the proposed architecture is known as the \gls{powerplant}.
-			The \gls{powerplant} is responsible for coordinating the various functions of the architecture and works behind the scenes to provide message handling.
-			Only one \gls{powerplant} exists can per program and the majority of the time the developers of the system will not directly interact with it.
-
-			The point of interaction that most users will see is called a \emph{\gls{reactor}}.
-			When a user wants to create a new feature they create a new class that inherits from \gls{reactor}.
-			This gives them access to the two key functions of the proposed architecture: \textbf{On} and
-			\textbf{Emit}.
-			\emph{On} allows users to specify reactions which behave as callbacks that are called when new data comes in.
-			For example: A reaction that is called when new image data is retrieved. \emph{Emit} allows \glspl{reactor} to send out a new
-			piece of data such as the sensor \gls{reactor} using \emph{Emit} to send new image data every
-			time it reads the camera hardware. \glspl{reactor} also provide one special type of event named
-			\textbf{Every} which lets you subscribe to an event that is guaranteed to tick at
-			consistent intervals. See Figure~\ref{fig:OnAndEmitExample} on
-			page~\pageref{fig:OnAndEmitExample} for an example of how \emph{On}, \emph{Emit} and
-			\emph{Every} are used.
+			The central authority of the proposed architecture is known as the \gls{powerplant} (Figure~\ref{fig:HighLevelProposedArchitecture} page~\pageref{fig:HighLevelProposedArchitecture}).
+			The \gls{powerplant} is responsible for the primary communication functions of the architecture through a publish/subscribe message passing system.
+			Only one \gls{powerplant} exists can per program and the majority of the time developers of the system will not directly interact with it.
 
+			The primary point of interaction for most users will be a \emph{\gls{reactor}}.
+			When a user wants to create a new feature they create a new class that inherits from gls{reactor}.
+			This gives them access to the key functionality of the proposed architecture. This functionality revolves around two functions, \textbf{On} and \textbf{Emit}.
+			
+			\emph{On} allows users to specify \glspl{reaction} which behave as callbacks that are activated when new data comes in. This is the method that is used to obtain data in a loosely coupled manner. The On method does not discriminate which component the data came from. This will be used by the robot in order to build on the results of previous components and perform logic.
+			
+			There are also a number of special types provided by the system.
+			These types can be used in an \emph{On} statement in order to get different behaviour.
+			The best example of this is the Every type. This type when used will make the system trigger the On method at regular intervals.
+			This functionality will be used by the NUBots as the primal events that trigger all of the sensor reads each round.
+			
+			\emph{Emit} allows \glspl{reactor} to push data into the \gls{powerplant} that will then distributed to all components that are interested in this datatype. This is done by calling their appropriate \emph{On} methods while providing the Emitted data as a paramter.
+			This will be used by the robot to push the results of any operations it has performed to allow other components to use them.
+			
+			An example: A Sensors reactor reads a camera frame every 30ms and uses \emph{Emit} to push a camera frame to the Power Plant. This is then received by the Vision system that processes the image and outputs the processed image it has created. This sequence of events is shown in Figure~\ref{fig:OnAndEmitExample} on page~\pageref{fig:OnAndEmitExample}.
+			
 			% On Emit and Every flow diagram
 			\begin{figure}[b]
 				\centering
 					\begin{scope}[start chain=going below, chained]
 
 						% Draw the Register node and setup the following blocks to have arrows
-						\node [block,join] (register) {Register reaction from \\ Vision system};
+						\node [block,join] (register) {Register \gls{reaction} from \\ Vision system};
 						\begin{scope}[start branch=on going right, every join/.style={<-}]
 							\node [block,join] (onimage) {on\textless \textbf{Image}\textgreater
 							\\(processimage)};
 							\textless ...\textgreater} events};
 
 						% Sensor Reactors node
-						\node [block, join, on chain=going left] {Execute reaction(s) \\for
+						\node [block, join, on chain=going left] {Execute \gls{reaction}(s) \\for
 							\textbf{Every\textless 30ms\textgreater}};
 
 						% Get Camera Image Node
 						\node [block, join] {Emit(\textbf{Image})};
 
 						% Image Call Node
-						\node [block, join, on chain=going right] {Call all reactions\\interested
+						\node [block, join, on chain=going right] {Call all \glspl{reaction}\\interested
 							in \textbf{Image}};
 
 						% Execute Reactions Node
-						\node [block, join, on chain=going right] {Execute reaction(s)\\for
+						\node [block, join, on chain=going right] {Execute \gls{reaction}(s)\\for
 							\textbf{Image}};
 
 						% Process Image Node
 				\label{fig:OnAndEmitExample}
 			\end{figure}
 
-			One of the key advantages of this design is that components are loosely coupled and only
-			depend on the data format not changing. This means that you could replace the
-			hardware-dependant camera system with a completely different module that reads a pre
-			recorded video stream for testing purposes. It also means that adding a new component to
-			the system merely requires that you know what sort of data you want to access. Gone are
-			they days of frantically trying to track down the obscure method used to access the
-			kinematics system. Instead you simply tell the system that you want the kinematics data
-			and then you have it!
-
-			Recent trends in computer hardware show that computational power increases are going
-			to come from increasing the number of cores available to the system.
+			One of the key advantages of this design is that components are loosely coupled and only depend on the data format not changing.
+			Therefore, you could replace the hardware dependent camera system with a new module that reads from a prerecorded video stream for testing purposes.
+			It also means that adding a new component to the system merely requires that you know what sort of data you want to access.
+			As there is a single way to get data, there is no longer a need to track down the obscure method used to access the needed data. Instead you simply tell the system the type that you require and the system locates it for you.
+
+			Recent trends in computer hardware show that computational power increases are going to come from increasing the number of cores available to the system.
 			Unfortunately the current system only takes advantage of at most two cores.
-			You wouldn't ride a horse that tried to gallop on a single leg and you wouldn't use an architecture
-			that didn't let you take full advantage of your processing resources.
+			The way that the system is currently architected enforces an artificial limitation on the resource utilisation of the system.
+			It would be inefficient to attempt to type with most of your fingers removed.
+			In a similar way not making use of all the resources on the platform limits the potential of the final result.
 			The proposed architecture takes care of multithreading transparently so the \gls{nubots} team can
-			focus on figuring out the important questions such "can this robot fetch me a pizza?".
-			When a reaction is triggered it doesn't necessarily run immediately.
-			Instead the reaction is put into a blocking priority queue and then executed on one of the many threads
+			focus on figuring out the important questions such ``can this robot fetch me a pizza?''.
+			When a \gls{reaction} is triggered it doesn't necessarily run immediately.
+			Instead the \gls{reaction} is put into a blocking priority queue and then executed on one of the many threads
 			available to the \gls{powerplant} via a thread pool.
-			For an example of how this system works see Figure~\ref{fig:PowerPlantThreadingOverviewDiagram} on
-			page~\pageref{fig:PowerPlantThreadingOverviewDiagram}.
+			For an example of how this system works see Figure~\ref{fig:PowerPlantThreadingOverviewDiagram} on page~\pageref{fig:PowerPlantThreadingOverviewDiagram}.
 
 			% Power Plant Threading Diagram
 			\begin{landscape}
 			\end{figure}
 			\end{landscape}
 
-			The client has also expressed how important it is that the robots be able to easily
-			communicate. Networking is a difficult and error-prone process which is why it's
-			imperative that the architecture provide a simple mechanism for robots to communicate.
-			The proposed architecture allows you to treat \glspl{reactor} on other robots as potential
-			targets for your data. This means you can emit data on one robot and receive it on any
-			of the other robots. See Figure~\ref{fig:NetworkExampleDiagram} on
-			page~\pageref{fig:NetworkExampleDiagram} for an example of how the networking system
-			allows robots to cooperate and share data.
+			The client has also expressed how important it is that the robots be able to easily communicate.
+			Networking is a difficult and error-prone process which is why it is imperative that the architecture provide a simple mechanism for robots to communicate.
+			The proposed architecture allows you to treat \glspl{reactor} on other robots as potential targets for your data.
+			This means you can emit data on one robot and receive it on any of the other robots.
+			See Figure~\ref{fig:NetworkExampleDiagram} on page~\pageref{fig:NetworkExampleDiagram} for an example of how the networking system allows robots to cooperate and share data.
 
 			% Networking diagram
 			\begin{figure}[b]