-\chapter{Design and Implementation}
+\chapter{Design and Implementation}\label{Design and Implementation}
% BEGIN Sam's section
As the revised diagram in Figure \ref{block_diagram_final.png} shows, to remove an extra layer of complexity it was decided to use a single device (the BeagleBone Black) to play the role of both the experiment server and the embedded device. From a software perspective, this eliminated the need for an entire layer of communication and synchronization. From a hardware perspective, use of the BeagleBone black instead of a Raspberry Pi removed the need to design or source analogue to digital conversion modules.
-Another major design change which occured quite early in the project is the switch from using multiple processes to running a single multithreaded process on the server. After performing some rudimentary testing (see Section \ref{Server Interface}) it became clear that a system of seperate programs would be difficult to implement and maintain. Threads are similar to processes but are able to directly share memory, with the result that much less synchronisation is required in order to transfer information.
+Another major design change which occurred quite early in the project is the switch from using multiple processes to running a single multithreaded process on the server. After performing some rudimentary testing (see Section \ref{Server Interface}) it became clear that a system of separate programs would be difficult to implement and maintain. Threads are similar to processes but are able to directly share memory, with the result that much less synchronisation is required in order to transfer information.
{\bf Note on filenames:} In the following, files and directories related to the server are located in the \href{https://github.com/szmoore/MCTX3420/tree/master/server}{server} directory, files related to the (currently used) GUI are in \href{https://github.com/szmoore/MCTX3420/tree/master/testing/MCTXWeb}{testing/MCTXWeb}, and files created for testing purposes are located in \href{https://github.com/szmoore/MCTX3420/tree/master/testing}{testing}.
The Server Program runs as a multithreaded process under a POSIX compliant GNU/Linux operating system\footnote{Tested on Debian and Ubuntu}. Each thread runs in parallel and is dedicated to a particular task; the three types of threads we have implemented are:
\begin{enumerate}
- \item Main Thread (Section \ref{Main Thread}) - Starts all other threads, accepts and responds to HTTP requests passed to the program by the HTTP server in the \funct{FastCGI_Loop} function (also see Section \ref{Communications})
+ \item Main Thread (Section \ref{Main Thread}) - Starts all other threads, accepts and responds to HTTP requests passed to the program by the HTTP server in the \funct{FastCGI_Loop} function (also see Section \ref{Server/Client Communication})
\item Sensor Thread (Section \ref{Sensor Thread}) - Each sensor in the system is monitored by an individual thread running the \funct{Sensor_Loop} function.
\item Actuator Thread (Section \ref{Actuator Thread}) - Each actuator in the system is controlled by an individual thread running the \funct{Actuator_Loop} function.
\end{enumerate}
-In reality, threads do not run simultaneously; the operating system is responsible for sharing execution time between threads in the same way as it shares execution times between processes. Because the linux kernel is not deterministic, it is not possible to predict when a given thread is actually running. This renders it impossible to maintain a consistent sampling rate, and necessitates the use of time stamps whenever a data point is recorded.
+In reality, threads do not run simultaneously; the operating system is responsible for sharing execution time between threads in the same way as it shares execution times between processes. Because the Linux kernel is not deterministic, it is not possible to predict when a given thread is actually running. This renders it impossible to maintain a consistent sampling rate, and necessitates the use of time stamps whenever a data point is recorded.
-Figure \ref{sample_rate_histogram.png} shows a distribution of times\footnote{The clock speed of the BeagleBone is between 200MHz and 700MHz (depends on power)\cite{cameon.net} which is fast enough to neglect the fact that recording the timestamp takes several CPU cycles} between samples for a test sensor with the software sampling as fast as possible. Note the logarithmic $t$ axis. Although context switching clearly causes the sample rate to vary (\textcolor{green}{green}), the actual process of reading an ADC (\textcolor{red}{red}) using \funct{ADC_Read} (\gitref{server}{bbb_pin.c}) is by far the greatest source of variation.
+Figure \ref{sample_rate_histogram.png} shows a distribution of times\footnote{The clock speed of the BeagleBone is around 1GHz\cite{bbb_specs}, which is fast enough to neglect the fact that recording the timestamp takes several CPU cycles.} between samples for a test sensor with the software sampling as fast as possible. Note the logarithmic $t$ axis. Although context switching clearly causes the sample rate to vary (\textcolor{green}{green}), the actual process of reading an ADC (\textcolor{red}{red}) using \funct{ADC_Read} (\gitref{server}{bbb_pin.c}) is by far the greatest source of variation.
-It was not possible to obtain a real time linux kernel for the BeagleBone. In theory, real time variants of the linux kernel improve the reliability of sampling rates. However, testing on an amd64 laptop showed very little difference in the sampling time distribution when the real time linux kernel was used.
+It was not possible to obtain a real time Linux kernel for the BeagleBone. In theory, real time variants of the Linux kernel improve the reliability of sampling rates. However, testing on an amd64 laptop showed very little difference in the sampling time distribution when the real time Linux kernel was used.
\begin{figure}[H]
\subsection{Main Thread}\label{Main Thread}
-The main thread of the process is responsible for transfering data between the server and the client through the Hypertext Transmission Protocol (HTTP). A library called FastCGI is used to interface with an existing webserver called nginx\cite{nginx}. This configuration and the format of data transferred between the GUI and the server is discussed in more detail Section \ref{Communications}.
+The main thread of the process is responsible for transferring data between the server and the client through the Hypertext Transmission Protocol (HTTP). A library called FastCGI is used to interface with an existing webserver called nginx\cite{nginx}. This configuration and the format of data transferred between the GUI and the server is discussed in more detail Section \ref{Server/Client Communication}.
-Essentially, the main thread of the process responds to HTTP requests. The GUI is designed to send requests periodically (eg: to update a graph) or when a user action is taken (eg: changing the pressure setting). When this is received, the main thread parses the request, the requested action is performed, and a response is sent. The GUI is then responsible for updating its appearance or alerting the user based on this response. Figure \ref{fastcgi-flow-chart.png} in Section \ref{API}gives an overview of this process.
+Essentially, the main thread of the process responds to HTTP requests. The GUI is designed to send requests periodically (e.g.: to update a graph) or when a user action is taken (e.g.: changing the pressure setting). When this is received, the main thread parses the request, the requested action is performed, and a response is sent. The GUI is then responsible for updating its appearance or alerting the user based on this response. Figure \ref{fastcgi-flow-chart.png} in Section \ref{API} gives an overview of this process.
\subsection{Sensor Threads}\label{Sensor Thread}
Figure \ref{sensor_thread.pdf} shows a flow chart for the thread controlling an individual sensor. This process is implemented by \verb/Sensor_Loop/ and associated helper functions.
-All sensors are treated as returning a single floating point number when read. A \type{DataPoint} consists of a time stamp and the sensor value. \type{DataPoint}s are continously saved to a binary file as long as the experiment is in process. An appropriate HTTP request (Section\ref{API}) will cause the main thread of the server program to respond with \type{DataPoint}s read back from the file. By using independent threads for reading data and transferring it to the GUI, the system does not rely on maintaining a consistent and synchronised network connection. This means that one the experiment is started with the desired parameters, a user can safely close the GUI or even shutdown their computer without impacting on the operation of the experiment.
+All sensors are treated as returning a single floating point number when read. A \type{DataPoint} consists of a time stamp and the sensor value. \type{DataPoint}s are continuously saved to a binary file as long as the experiment is in process. An appropriate HTTP request (Section \ref{API}) will cause the main thread of the server program to respond with \type{DataPoint}s read back from the file. By using independent threads for reading data and transferring it to the GUI, the system does not rely on maintaining a consistent and synchronised network connection. This means that one the experiment is started with the desired parameters, a user can safely close the GUI or even shutdown their computer without impacting on the operation of the experiment.
\subsection{Actuator Threads}\label{Actuator Thread}
-Actuators are controlled by threads in a similar way to sensors. Figure \ref{actuator_thread.pdf} shows a flow chart for these threads. This is implemented in \verb/Actuator_Loop/. Control over real hardware is seperated from the main logic in the same way as sensors (relevant files are in the \verb/actuators/ sub directory). The use of threads to control actuators gives similar advantages in terms of eliminating the need to syncronise the GUI and server software.
+Actuators are controlled by threads in a similar way to sensors. Figure \ref{actuator_thread.pdf} shows a flow chart for these threads. This is implemented in \verb/Actuator_Loop/. Control over real hardware is separated from the main logic in the same way as sensors (relevant files are in the \verb/actuators/ sub directory). The use of threads to control actuators gives similar advantages in terms of eliminating the need to synchronise the GUI and server software.
The actuator thread has been designed for flexibility in how exactly an actuator is controlled. Rather than specifying a single value, the main thread initialises a structure that determines the behaviour of the actuator over a period of time. The current structure represents a simple set of discrete linear changes in the actuator value. This means that a user does not need to specify every single value for the actuator. The Actuator thread stores a value every time the actuator is changed which can be requested in a similar way to sensor data.
\subsection{Data Storage and Retrieval}
-Each sensor or actuator thread stores data points in a seperate binary file identified by the name of the device. When the main thread receives an appropriate HTTP request, it will read data back from the binary file. To allow for selection of a range of data points from the file, a binary search has been implemented. Functions related to data storage and retrieval are located in the \gitref{server}{data.h} and \gitref{server}{data.c} source files.
+Each sensor or actuator thread stores data points in a separate binary file identified by the name of the device. When the main thread receives an appropriate HTTP request, it will read data back from the binary file. To allow for selection of a range of data points from the file, a binary search has been implemented. Functions related to data storage and retrieval are located in the \gitref{server}{data.h} and \gitref{server}{data.c} source files.
Several alternate means of data storage were considered for this project. Binary files were chosen because of the significant performance benefit after testing, and the ease with which data can be read from any location in file and converted directly into values. A downside of using binary files is that the server software must always be running in order to convert the data into a human readable format.
Given the inexperienced nature of the software team, the limited development time, and the unclear specifications, it is not wise to trust safety aspects of the system to software alone. It should also be mentioned that the correct functioning of the system is reliant not only upon the software written during this project, but also the many libraries which are used, and the operating system under which it runs. We found during development that many of the mechanisms for controlling BeagleBone hardware are unreliable and have unresolved issues; see the project wiki pages\cite{mctx3420_wiki} for more information. We attempted to incorporate safety mechanisms into the software wherever possible.
-Sensors and Actuators should define an initialisation and cleanup function. For an actuator (eg: the pressure regulator), the cleanup function must set the actuator to a predefined safe value (in the case of pressure, atmospheric pressure) before it can be deinitialised. In the case of a software error or user defined emergency, the \funct{Fatal} function can be called from any point in the software; this will lead to the cleanup functions of devices being called, which will in turn lead to the pressure being set to a safe value.
+Sensors and Actuators should define an initialisation and cleanup function. For an actuator (e.g.: the pressure regulator), the cleanup function must set the actuator to a predefined safe value (in the case of pressure, atmospheric pressure) before it can be uninitialised. In the case of a software error or user defined emergency, the \funct{Fatal} function can be called from any point in the software; this will lead to the cleanup functions of devices being called, which will in turn lead to the pressure being set to a safe value.
Sensors and Actuators are designed to include an optional \funct{sanity} function which will check a reading or setting is safe respectively. These checks occur whenever a sensor value is read or an actuator is about to be set. In the case of a sensor reading failing the sanity check, \funct{Fatal} is called immediately and the software shuts down the experiment. In the case of an actuator being set to an unsafe value the software will simply refuse to set the value.
\end{figure}
-\section{Hardware Interfacing}\label{Hardware}
+\section{Hardware Interfacing}\label{Hardware Interfacing}
Figure \ref{pinout.pdf} shows the pin out diagram of the BeagleBone Black. There are many contradictory pin out diagrams available on the internet; this figure was initially created by the software team after trial and error testing with an oscilloscope to determine the correct location of each pin. Port labels correspond with those marked on the BeagleBone PCB. The choice of pin allocations was made by the electrical team after discussion with software when it became apparent that some pins could not be controlled reliably.
\subsubsection{Relay Controls}
-The electrical team employed three relays (model: ) for control over digital devices. The relays are switched using the GPIO outputs of the BeagleBone Black.
+The electrical team employed three relays for control over digital devices. The relays are switched using the GPIO outputs of the BeagleBone Black.
\begin{itemize}
\item Can select - Chooses which can can be pressurised (0 for strain, 1 for explode)
\subsubsection{PWM Outputs}
-A single PWM output is used to control a pressure regulator (model: ). The electrical team constructed an RC filter circuit which effectively averages the PWM signal to produce an almost constant analogue output. The period of the PWM is $2\text{kHz}$. This actuator has been calibrated, which allows the user to input the pressure value in kPa rather than having to control the PWM duty cycle corretly.
+A single PWM output is used to control a pressure regulator. The electrical team constructed an RC filter circuit which effectively averages the PWM signal to produce an almost constant analogue output. The period of the PWM is $2\text{kHz}$. This actuator has been calibrated, which allows the user to input the pressure value in kPa rather than having to control the PWM duty cycle correctly.
\begin{figure}[H]
\end{figure}
-\section{Authentication Mechanisms}\label{Authentication}
+\section{Authentication Mechanisms}\label{Authentication Mechanisms}
The \funct{Login_Handler} function (\gitref{server}{login.c}) is called in the main thread when a HTTP request for authentication is received (see Section \ref{Communication}). This function checks the user's credentials and will give them access to the system if they are valid. Whilst we had originally planned to include only a single username and password, changing client requirements forced us to investigate many alternative authentication methods to cope with multiple users.
\item {\bf Unix style authentication}
- Unix like operating systems store a plain text file (/etc/shadow) of usernames and encrypted passwords. To check a password is valid, it is encrypted and then compared to the stored encrypted password. The actual password is never stored anywhere. The /etc/shadow file must be maintained by shell commands run directly from the BeagleBone. Alternatively a web based system to upload a similar file may be created.
+ Unix like operating systems store a plain text file (/etc/shadow) of usernames and encrypted passwords\cite{shadow}. To check a password is valid, it is encrypted and then compared to the stored encrypted password. The actual password is never stored anywhere. The /etc/shadow file must be maintained by shell commands run directly from the BeagleBone. Alternatively a web based system to upload a similar file may be created.
\item {\bf Lightweight Directory Access Protocol (LDAP)}
- LDAP is a widely used data base for storing user information. A central server is required to maintain the LDAP database; programs running on the same network can query the server for authentication purposes.
+ LDAP\cite{ldap, ldap_man} is a widely used data base for storing user information. A central server is required to maintain the LDAP database; programs running on the same network can query the server for authentication purposes.
The UWA user management system (Pheme) employs an LDAP server for storing user information and passwords. The software has been designed so that it can interface with an LDAP server configured similarly to the server on UWA's network. Unfortunately we were unable to gain permission to query this server. However an alternative server could be setup to provide this authentication mechanism for our system.
\item {\bf MySQL Database}
- MySQL is a popular and free database system that is widely used in web applications. The ability to search for a user in a MySQL database and check their encrypted password was added late in the design as an alternative to LDAP. There are several existing online user management systems which interface with a MySQL database, and so it is feasable to employ one of these to maintain a list of users authorised to access the experiment. UserCake is recommended, as it is both minimalistic and open source, so can be modified to suit future requirements. We have already begun integration of the UserCake system into the project, however a great deal of work is still required.
+ MySQL\cite{mysql} is a popular and free database system that is widely used in web applications. The ability to search for a user in a MySQL database and check their encrypted password was added late in the design as an alternative to LDAP. There are several existing online user management systems which interface with a MySQL database, and so it is feasible to employ one of these to maintain a list of users authorised to access the experiment. UserCake\cite{UserCake} is recommended, as it is both minimalistic and open source, so can be modified to suit future requirements. We have already begun integration of the UserCake system into the project, however a great deal of work is still required.
MySQL and other databases are vulnerable to many different security issues which we did not have sufficient time to fully explore. Care should be taken to ensure that all these issues are addressed before deploying the system.
% END Sam's section
-\section{Server/Client Communication}\label{Communications}
+\section{Server/Client Communication}\label{Server/Client Communication}
% BEGIN Jeremy's section
-This section describes the methods and processes used to communicate between the server and client. For this system, client-server interaction is achieved completely over the internet, via standard HTTP web requests with TLS encryption. In other words, it has been designed to interact with the client over the internet, {\bf completely through a standard web browser} (Figure \ref{client_request_flowchart.png}). No extra software should be required from the client. Detailed reasons for this choice are outlined in Section \ref{Alternative Communication}
+This section describes the methods and processes used to communicate between the server and client. For this system, client-server interaction is achieved completely over the internet, via standard HTTP web requests with TLS encryption. In other words, it has been designed to interact with the client over the internet, {\bf completely through a standard web browser} (Figure \ref{client_request_flowchart.png}). No extra software should be required from the client. Detailed reasons for this choice are outlined in Section \ref{Alternative Communication Technologies}
\begin{figure}[H]
\centering
- \includegraphics[width=1.1\textwidth]{figures/client_request_flowchart.png}
+ \includegraphics[width=0.8\textwidth]{figures/client_request_flowchart.png}
\caption{High level flow chart of a client request to server response}
\label{client_request_flowchart.png}
\end{figure}
Transport Layer Security (TLS) encryption, better known as SSL or HTTPS encryption has been enabled to ensure secure communications between the client and server. This is primarily important for when user credentials (username / password) are supplied, and prevents what is called ``man-in-the-middle'' attacks. In other words, it prevents unauthorised persons from viewing such credentials as they are transmitted from the client to the server.
-As also mentioned in Section \ref{Authentication} this system also runs a MySQL server for the user management system, UserCake. This kind of server setup is commonly referred to as a LAMP (Linux, Apache, MySQL, PHP) configuration\cite{}, except in this case, nginx has been used in preference to the Apache web server.
+As also mentioned in Section \ref{Authentication Mechanisms} this system also runs a MySQL server for the user management system, UserCake. This kind of server setup is commonly referred to as a LAMP (Linux, Apache, MySQL, PHP) configuration\cite{lamp}, except in this case, nginx has been used in preference to the Apache web server.
Nginx was used as the web server because it is well established, lightweight and performance oriented. It also supports FastCGI by default, which is how nginx interfaces with the server program. Realistically, any well known web server would have sufficed, such as Apache or Lighttpd, given that this is not a large scale service.
\begin{figure}[H]
\centering
- \includegraphics[width=1.1\textwidth]{figures/fastcgi-flow-chart.png}
+ \includegraphics[width=0.9\textwidth]{figures/fastcgi-flow-chart.png}
\caption{Flow chart of a client request being processed (within the server program). Relevant files are \gitref{server}{fastcgi.c} and \gitref{server}{fastcgi.h}.}
\label{fastcgi-flow-chart.png}
\end{figure}
\url{https://host/api/module?key1=value1&key2=value2...&keyN=valueN} (where \verb/host/ is replaced with the IP address or hostname of the server).
-The API consists of modules that can accept a certain number of arguments (specified as key-value pairs), depending on what that module (Figure \ref{modules}) does. For example, to query the API about basic information (running state, whether the user is logged in etc), the following query is used:
+The API consists of modules accepting arguments (specified as key-value pairs), depending on what that module (Figure \ref{modules}) does. For example, to query the API about basic information (running state, whether the user is logged in etc), the following query is used:
\url{https://host/api/identify}
This request handling code went through a number of iterations before the final solution was reached. Changes were made primarily as the number of modules grew, and as the code was used more.
-One of the greatest changes to request handling was with regards to how parameters were parsed. Given a request of: \url{http://host/api/actuators?name=pregulator\&start_time=0\&end_time=2}, The module handler would receive as the parameters \texttt{name=pregulator\&start_time=0\&end_time=2}. This string had to be split into the key/value pairs to be used, which resulted in the function \funct{FCGI_KeyPair} being made, which was initially sufficient for most cases.
+One of the greatest changes to request handling was with regards to how parameters were parsed. Given a request of: \url{http://host/api/actuators?name=pregulator\&start_time=0\&end_time=2}, The module handler would receive as the parameters \texttt{name=pregulator\&start_time=0\&end_time=2}. This string had to be split into the key/value pairs, so the function \funct{FCGI_KeyPair} being made.
-However, as more module handlers were created, and as the number of parameters required increased, \funct{FCGI_KeyPair} became increasingly cumbersome to use. \funct{FCGI_ParseRequest} was created in response, and internally uses \funct{FCGI_KeyPair}, but abstracts request parsing greatly. In essence, it validates the user input, rejecting anything that doesn't match a specified format. If it passes this test, it automatically populates variables with these values. The \funct{IndentifyHandler} module handler in \gitref{server}{fastcgi.c} is a very good example of how this works.
+With increased usage, this was found to be insufficient. \funct{FCGI_ParseRequest} was created in response, and internally uses \funct{FCGI_KeyPair}, but abstracts request parsing greatly. In essence, it validates the user input, rejecting anything that doesn't match a specified format. If it passes this test, it automatically populates variables with these values. The \funct{IndentifyHandler} module handler in \gitref{server}{fastcgi.c} is a very good example of how this works.
\begin{figure}[H]
\centering
"control_state" : "Running",
"description" : "MCTX3420 Server API (2013)",
"build_date" : "Oct 24 2013 19:41:04",
- "clock_getres" : 0.000000001,
"api_version" : 0,
"logged_in" : true,
"user_name" : "_anonymous_noauth"
To generate the JSON response from the server program, \gitref{server}{fastcgi.c} contains a framework of helper functions. Most of the functions help to ensure that the generated output is in a valid JSON format, although only a subset of the JSON syntax is supported. Supporting the full syntax would overcomplicate writing the framework while being of little benefit. Modules can still respond with whatever format they like, using \funct{FCGI_JSONValue} (aka. \funct{FCGI_PrintRaw}), but lose the guarantee that the output will be in a valid JSON format.
-Additionally, not all responses are in the JSON format. In specific cases, some module handlers will respond in a more suitable format. For example, the image handler will return an image (using \funct{FCGI_WriteBinary}); it would make no sense to return anything else. On the other hand, the sensor and actuator modules will return data as tab-separated values, if the user specifically asks for it (eg: using \url{https://host/api/sensors?id=X&format=tsv})
+Additionally, not all responses are in the JSON format. In specific cases, some module handlers will respond in a more suitable format. For example, the image handler will return an image (using \funct{FCGI_WriteBinary}); it would make no sense to return anything else. On the other hand, the sensor and actuator modules will return data as tab-separated values, if the user specifically asks for it (e.g.: using \url{https://host/api/sensors?id=X&format=tsv})
\subsection{Server API - Cookies}\label{Cookies}
Whilst AJAX requests are possible with plain JavaScript, the use of the jQuery library (see Section \ref{jQuery}) greatly simplifies the way in which requests can be made and interpreted.
-\section{Alternative Communication Technologies}\label{Alternative Communication}
+\section{Alternative Communication Technologies}\label{Alternative Communication Technologies}
This section attempts to explain the reasoning behind the communication method chosen. This choice was not trivial, as it had to allow for anyone to remotely control the experiment, while imposing as little requirements from the user as possible. These requirements can be summarised by:
\begin{enumerate}
\label{cgi.png}
\end{figure}
-Initially, a system known as ``Common Gateway Interface'', or CGI was explored. However, CGI based software is only executed when a request is received (Figure \ref{cgi.png}, which makes continuous control and logging over the sensors and actuators unfeasible.
+Initially, a system known as ``Common Gateway Interface'', or CGI was explored. However, CGI based software is only executed when a request is received (Figure \ref{cgi.png}), which makes continuous control and logging over the sensors and actuators unfeasible.
\begin{figure}[H]
\centering
\includegraphics[width=0.8\textwidth]{figures/custom_webserver.png}
- \caption{Block Diagram of a request to a custom webserver}
+ \caption{Block Diagram of a request to a custom web server}
\label{custom_webserver.png}
\end{figure}
-Before FastCGI was found, the plan was to build a custom web server (Figure \ref{custom_webserver.png} that used threading. Both the sensor/actuator control and the web interface would reside in the same process. By having both in the same process, continuous control is possible whilst waiting for web requests to be received.
-
-This would have worked, and in fact operates similarly to the final solution, but it was not without drawbacks. By building a custom web server, more effort would have to be spent just to maintain low-level web functionalities, such as responding appropriately to a client request. Perhaps more importantly, features taken for granted from a standard web server would become increasingly difficult to support with a custom web server. For example, services like TLS encryption and PHP support would be near-impossible, or at least very difficult to add. In other words, it was deemed that this solution would be inflexible and not particularly maintainable into the future.
+Another system considered was to build a custom web server (Figure \ref{custom_webserver.png}) that used threading, integrating both the control and web components. This option was primarily discarded because it was inflexible to supporting extended services like PHP and TLS encryption. See \href{https://github.com/szmoore/MCTX3420/issues/6}{Issue 6} on GitHub for more information.
\begin{figure}[H]
\centering
\begin{enumerate}
\item A self-signed TLS certificate has been used, as it is free. It is equally secure as any, but users will get a security warning when accessing the web site. A proper TLS certificate signed by a trusted certificate authority should be used instead.
\item Consider expanding the framework of JSON functions to simplify creating a response.
- \item Consider using X-Accel-Redirect along with UserCake (Section \ref{Authentication}) to make a finer-grained access control system to information such as the system logs
+ \item Consider using X-Accel-Redirect along with UserCake (Section \ref{Authentication Mechanisms}) to make a finer-grained access control system to information such as the system logs
\end{enumerate}
-\section{Server Configuration}
+\section{BeagleBone Configuration}\label{BeagleBone Configuration}
\subsection{Operating system}
The Beaglebone has been configured to use the Ubuntu operating system. The original operating system was Angstrom, which was unsuitable because it lacked a number of software packages required. Detailed instructions on how to install this operating system exist on the project wiki\cite{mctx3420_wiki}.
Specifically, there was much grief over getting the pins to function correctly, especially for PWM output. Lacking any great documentation, much trial and error was spent determining the best configuration. The BeagleBone Black uses what is termed a ``device tree'' \cite{beaglebone3.8, devicetreetutorial} and ``device tree overlays'' to dynamically determine what each pin does. This is because each pin can have more than one function, so a ``device tree overlay'' determines what it does at any one point. However, this also complicates matters, since what pins do essentially have to be loaded at runtime.
-PWM control in particular took many hours to achieve, which was not helped by a lot of conflicting information available online. As a result, the primary tool used to correctly determine proper PWM control was the use of a cathode ray oscilloscope. Quite briefly, it was found that certain actions had to be performed in a very specific order to make PWM control available. There were also specific limitations, such as pairs of pins being coupled to the same time base (period). The wiki goes into more detail on the issues found.
+PWM control in particular took many hours to achieve, which was not helped by a lot of conflicting information available online. As a result, the primary tool used to correctly determine proper PWM control was the use of a cathode ray oscilloscope. Quite briefly, it was found that certain actions had to be performed in a very specific order to make PWM control available. The wiki goes into more detail on the issues found.
Getting the cameras to work on the BeagleBone was another major issue faced. After much testing, it was simply found that the cameras could only work on the latest version of the operating system. On anything else, only low resolution captures of around 352x288 pixels could be achieved.
-Finally, it should be noted that USB hotplugging does not work on the BeagleBone. This means that the cameras have to be plugged in before booting the BeagleBone. Upgrading to a newer kernel (when it exists) should solve this issue.
+Finally, it should be noted that USB hot-plugging does not work on the BeagleBone. This means that the cameras have to be plugged in before booting the BeagleBone. Upgrading to a newer kernel (when it exists) should solve this issue.
\subsection{Required software}
These packages should be installed with the command \texttt{apt-get install}.
\subsection{Required configurations}
-Many components need to be configured correctly for the server to work. In particular, these configurations relate to the web server, nginx, as well as logging software used, rsyslog. These configurations are automatically installed by a specific script on the git repository.
-
-There is a folder, labelled server-configs. Executing \gitref{server-configs}{install.sh} as root should install all the required configuration files to run the server correctly.
+Many components need to be configured correctly for the server to work. In particular, these configurations relate to the web server, nginx, as well as logging software used, rsyslog. Executing \gitref{server-configs}{install.sh} as root should install all the required configuration files to run the server correctly.
% END Jeremy's section
The Canny Edge algorithm\cite{OpenCV_Canny} determines which pixels are ``edge'' pixels through a series of steps. The algorithm applies the Sobel operator in the x and y directions using \var{KERNELSIZE} for the size of the kernel. The result of this gives the gradient strength and direction. The direction is rounded to 0, 45, 90 or 135 degrees. Non-maximum suppression is then used to remove any pixels not considered to be part of an edge. The pixels left are then put through the hysteresis step. If the gradient of the pixel is higher than the upper threshold (in our algorithm denoted by \var{LOWTHRESHOLD*RATIO}) then the pixel is accepted as an edge. If it is below the lower threshold (i.e. \var{LOWTHRESHOLD}) then the pixel is disregarded. The remaining pixels are removed unless that is connected to a pixel above the upper threshold (Canny Edge Detector). The defined values in the header file can be altered to improve accuracy.
-The \funct{CannyThreshold} function fills the \type{CvMat} \var{g_edges} structure with the current images edge (i.e. an image containing only pixels considering to be edges, see Appendix \ref{appendix_imageedge} ). The code then finds the location of the line. It does this by sampling a number of rows, determined by the number of samples and the height of the image, finding the pixel/s in the row considered to be an edge. The algorithm then takes the average position of these pixels. The average position over all rows sampled then determines the actual edge position. The rows sampled are evenly spaced over the height of the image. If a row does not contain an edge, then it will not be included in the average. If a blank image goes through, or the algorithm has a low number of samples and does not pick up an edge, then the function will return false and the data point will not be recorded.
+The \funct{CannyThreshold} function fills the \type{CvMat} \var{g_edges} structure with the current image edge (i.e. an image containing only pixels considering to be edges, see Appendix \ref{appendix_imageedge} ). The code then finds the location of the line. It does this by sampling a number of rows, determined by the number of samples and the height of the image, finding the pixel/s in the row considered to be an edge. The algorithm then takes the average position of these pixels. The average position over all rows sampled then determines the actual edge position. The rows sampled are evenly spaced over the height of the image. If a row does not contain an edge, then it will not be included in the average. If a blank image goes through, or the algorithm has a low number of samples and does not pick up an edge, then the function will return false and the data point will not be recorded.
Once the edge is found, we will either return the position of the edge, if the \var{DIL_POS} ID is set. It needs to be noted that this will only show the change in position of one side of the can. If the \var{DIL_DIFF} ID is set then the value will be set to the difference between the current position and the last position, multiplied by \var{SCALE} and 2. We need to multiply by 2 as we are only measuring the change in width to one side of the can, however we must assume that the expansion is symmetrical. The scale will be used to convert from pixels to $\mu$m (or a more suitable scale). Currently the scale is set to 1, as the dilatometer has not been calibrated, thus we are only measuring the rate of change of pixels (which is arbitrary). The static variable, \var{lastPosition}, is then set to determine the next change in size. If the difference is negative, then the can is being compressed or is being depressurized.
The rate of expansion can then be determined from the data set. As the system does not have a fixed refresh rate, however each data point is time-stamped. If the data is the edge position, then plotting the derivative of the time graph will show the rate of expansion over time.
\label{canny_edges_noise.png}
\end{figure}
-After the Sensors Team relayed that they were now attaching something to the can in order to measure the change position, I decided to simply stick with the Canny Edge algorithm and implement something similar to what I had in my previous testing. The figures in appendix A shows the progression of the image through the algorithm. Figure 2A shows the original image, whereas 2B shows the blurred (with a BLUR value of 5) gray scale image. Whereas figure 2C shows the image after going through the Canny Edge algorithm with a low threshold of 35. Figures 3A and 3B both have the same input image, however different input values. It can be seen how tweaking the values can remove outliers, as figure 3B is skewed to the right due to the outliers. From figure 4 it can be seen that despite there being no points in the edge in the top half of the image, the edge has still been accurately determined.
+After the Sensors Team relayed that they were now attaching something to the can in order to measure the change position, I decided to simply stick with the Canny Edge algorithm and implement something similar to what I had in my previous testing. The images in Figure \ref{canny_demo} shows the progression of the image through the algorithm. Figure \ref{canny_demo} A shows the original image, whereas \ref{canny_demo}B shows the blurred (with a BLUR value of 5) gray scale image. Whereas figure \ref{canny_demo}C shows the image after going through the Canny Edge algorithm with a low threshold of 35. Figures \ref{canny_demo}D and \ref{canny_demo}E both have the same input image, however different input values. It can be seen how tweaking the values can remove outliers, as figure \ref{canny_demo}E is skewed to the right due to the outliers. From figure \ref{canny_demo}F it can be seen that despite there being no points in the edge in the top half of the image, the edge has still been accurately determined.
The testing done shows that given a rough edge with few outliers an edge can be determined, however there is an obvious degree of inaccuracy the greater the variance of the edge. The best solution to this however does not lie in software. If an edge was used that was straight even at that magnification with a good contrast then the results would be much more accurate (i.e. the accuracy of the dilatometer is currently more dependent on the object used than the software).
\item The algorithm can be improved to try and neglect outliers in the edge image; however this is not as necessary if the original object used gives a sufficiently smooth and straight edge.
\end{itemize}
-% END Callum's section
-
\subsection{Results}
-Figure \ref{image_in_api.png} shows an image obtained from one of two dilatometers used in the system setup with collaboration between all teams. The image is of a white lego tile attached to the can. This image was successfully streamed using the server software, and results of the dilatometer readings were monitored using the same software. Unfortunately we were unable to maintain a constant value for a stationary can, indicating that the algorithm needs further development. Due to a leak in the can seal we were unable to pressurize the can sufficiently to see a noticable change in the edge position.
+Figure \ref{image_in_api.png} shows an image obtained from one of two dilatometers used in the system setup with collaboration between all teams. The image is of a white Lego tile attached to the can. This image was successfully streamed using the server software, and results of the dilatometer readings were monitored using the same software. Unfortunately we were unable to maintain a constant value for a stationary can, indicating that the algorithm needs further development. Due to a leak in the can seal we were unable to pressurize the can sufficiently to see a noticeable change in the edge position.
\begin{figure}[H]
\centering
\includegraphics[width=0.6\textwidth]{figures/image_in_api.png}
- \caption{Microscope image of actual lego tile attached to can in experimental setup}
+ \caption{Microscope image of actual Lego tile attached to can in experimental setup}
\label{image_in_api.png}
\end{figure}
+\begin{figure}[H]
+ \centering
+
+ \begin{tabular}{cc}
+ \includegraphics[width=0.4\textwidth]{figures/dilatometer_test.jpg} A &
+ \includegraphics[width=0.4\textwidth]{figures/dilatometer_test.jpg} B \\
+ \includegraphics[width=0.4\textwidth]{figures/dila_blur7thresh36.png} C &
+ \includegraphics[width=0.4\textwidth]{figures/dila_blur5thresh30.png} D \\
+ \includegraphics[width=0.4\textwidth]{figures/dila_blur9thresh35.png} E &
+ \includegraphics[width=0.4\textwidth]{figures/dila_blur9thresh35_2.png} F
+ \end{tabular}
+ \caption{Canny Edge Algorithm in Action}
+ \label{canny_demo}
+\end{figure}
+
+% END Callum's section
+
+
+
-\section{Human Computer Interaction and the Graphical User Interface}
+\section{Human Computer Interaction and the Graphical User Interface}\label{Human Computer Interaction and the Graphical User Interface}
% BEGIN James' section
\subsection{Design Considerations}
Due to the limits of the Beagle Bone such as available memory and processing power it was important that the code, images and all libraries used were both small in size and efficient. This meant that careful consideration had to be made every time a library was considered for use. It also meant that where possible processing should be offloaded onto the client hardware rather than running on the server which already runs the server side code. This meant large libraries were ruled out and actions such as graphing were performed by the GUI on the client machine.
- The final consideration is extensibility. An extensible software base code allows easy addition of new features. A good extensible interface makes it a simple case of simply dropping the extra code in in order to add extra features whereas a GUI that doesn't take this into account can require deleting and recoding of large chunks of the previous code. This means that the interface code must be structured in a coherent way and all conform to a ``standard'' across the GUI. Code must be laid out in the same way from page to page and where possible sections of code facilitating specific goals should be removed from the main page code. The latter was achieved through the use of the \verb/.load()/ JavaScript function allowing whole widgets to be removed and placed in their own seperate files. This feature alone lets the developer add new widgets simply by creating a widget file conforming to the GUI's standard and then \verb/.load()/ it into the actual page.
+ The final consideration is extensibility. An extensible software base code allows easy addition of new features. A good extensible interface makes it a simple case of simply dropping the extra code in in order to add extra features whereas a GUI that doesn't take this into account can require deleting and recoding of large chunks of the previous code. This means that the interface code must be structured in a coherent way and all conform to a ``standard'' across the GUI. Code must be laid out in the same way from page to page and where possible sections of code facilitating specific goals should be removed from the main page code. The latter was achieved through the use of the \verb/.load()/ JavaScript function allowing whole widgets to be removed and placed in their own separate files. This feature alone lets the developer add new widgets simply by creating a widget file conforming to the GUI's standard and then \verb/.load()/ it into the actual page.
\subsection{Libraries used in GUI construction}
Flot\cite{flot} is a Javascript library designed for plotting and built for jQuery. This a lightweight easy to use library that allows easy production of attractive graphs. It also includes advanced support for interactive features and can support for $\text{IE} < 9$ . The Flot library provided an easy but powerful way to graph the data being sent by the server.
-\subsection{Libraries trialed but not used in GUI construction}
+\subsection{Libraries trialled but not used in GUI construction}
These are libraries that were looked at and considered for use in the GUI software but were decided to not be used in the final product.
\begin{figure}[H]
\centering
\includegraphics[width=0.8\textwidth]{figures/draftGUI.png}
- \caption{Draft GUI designed in Microsoft Powerpoint}
+ \caption{Draft GUI designed in Microsoft PowerPoint}
\label{draftGUI.png}
\end{figure}
% BEGIN Rowan's section
-\section{GUI Design Process}
+\section{GUI Design Process}\label{GUI Design Process}
\subsection{Creation}
\begin{figure}[H]
\centering
- \includegraphics[width=0.8\textwidth]{figures/GUI_creation.png}
+ \includegraphics[width=0.8\textwidth]{figures/gui_creation.png}
\caption{First Test GUI}
\end{figure}
\begin{figure}[H]
\centering
- \includegraphics[width=0.8\textwidth]{figures/GUI_creation.png}
+ \includegraphics[width=0.8\textwidth]{figures/gui_creation.png}
\caption{Testing GUI}
\end{figure}
\subsection{Parallel GUI Design}
-During the GUI development phase, several GUIs were created. Some used graphical development software, while others used hard codded HTML, JavaScript, and CSS. Due to no organization within the group and a lack in communication a ``final GUI'' was made by several of the team members. Some of theses are shown below.
+During the GUI development phase, several GUIs were created. Some used graphical development software, while others used hard coded HTML, JavaScript, and CSS. Due to no organization within the group and a lack in communication a ``final GUI'' was made by several of the team members. Some of these are shown below.
\subsection{GUI Aesthetics}
-Once we had decided on our core GUI design, we decided that, although not yet complete we would get Adrain Keatings opinion on the GUI design. While the GUI design was simple and functional Dr. Keating pointed out the design was bland. He encouraged us to release our artistic flair onto our GUI and make it more graphical and easy to use. Taking this into account we began work on another final GUI designing almost from scratch. We kept our GUI design flow, and worked largely on the look and feel of the GUI rather the functionality the GUI needed.
+Once we had decided on our core GUI design, we decided that, although not yet complete we would get Adrian Keating's opinion on the GUI design. While the GUI design was simple and functional Dr. Keating pointed out the design was bland. He encouraged us to release our artistic flair onto our GUI and make it more graphical and easy to use. Taking this into account we began work on another final GUI designing almost from scratch. We kept our GUI design flow, and worked largely on the look and feel of the GUI rather the functionality the GUI needed.
\subsection{HTML Structure}
\subsection{Graphical Development VS Hard Coding}
-From the Multiple GUI we had accidently created during the GUI design phase we noticed a large variety in the styles of GUIs that came out (Which shouldn't have happened) GUIs were created using HTML CSS and JavaScript being hard coded, from development software like Dreamweaver, and various Java based development platforms.
+From the Multiple GUI we had accidentally created during the GUI design phase we noticed a large variety in the styles of GUIs that came out (Which shouldn't have happened) GUIs were created using HTML CSS and JavaScript being hard coded, from development software like Dreamweaver, and various Java based development platforms.
\subsection{Final Design}
\begin{figure}[H]
\centering
- \includegraphics[width=0.8\textwidth]{figures/GUI_final.png}
+ \includegraphics[width=0.8\textwidth]{figures/gui_final.png}
\caption{Final GUI}
\end{figure}
\begin{figure}[H]
\centering
- \includegraphics[width=0.8\textwidth]{figures/GUI_experiment.png}
+ \includegraphics[width=0.8\textwidth]{figures/gui_experiment.png}
\caption{The Experiment (While disconnected from the server in the pic above) displays the Warnings and the experiment state to allow device use by only 1 student and avoid nasty conflicting control}
\end{figure}
\begin{figure}[H]
\centering
- \includegraphics[width=0.8\textwidth]{figures/GUI_results.png}
+ \includegraphics[width=0.8\textwidth]{figures/gui_results.png}
\caption{The Experimental Results page (also currently disconnected)}
\end{figure}
\begin{figure}[H]
\centering
- \includegraphics[width=0.8\textwidth]{figures/GUI_data.png}
+ \includegraphics[width=0.8\textwidth]{figures/gui_data.png}
\caption{The experimental data page shows the start the sensors and actuators are reading, useful for checking the condition and measuring the experiment. }
\end{figure}
\begin{figure}[H]
\centering
- \includegraphics[width=0.8\textwidth]{figures/GUI_pintest.png}
+ \includegraphics[width=0.8\textwidth]{figures/gui_pintest.png}
\caption{The BBB Pin test page is for the software team only so that we can test and debug the experiment we errors are found in the GUI or software. }
\end{figure}
\begin{figure}[H]
\centering
- \includegraphics[width=0.8\textwidth]{figures/GUI_help.png}
+ \includegraphics[width=0.8\textwidth]{figures/gui_help.png}
\caption{The help page, which links to the wiki information from all the teams and allows new users to look at all aspects of the project to be further developed and finished. }
\end{figure}
git.ucc.asn.au / matches / MCTX3420.git / blobdiff
UCC git Repository :: git.ucc.asn.au