current refactoring state

1-introduction.tex

@@ -9,8 +9,8 @@ In embedded systems, the software, also known as firmware, is an essential part
 On one side, it interacts with the hardware in a system specific way by implementing the specifications required by the components used in the system.
 On the other side, it provides use-case dependent functionality in interaction with general purpose hardware components.
 Embedded systems are often thought as systems that never change their requirements or functionality.
-However, practical use shows that the environment in which these systems run do, in fact, change.
-These changes include, but are not limited to, modifications to the expected behavior or additions to it, reconfiguration of parameters related to communication with other systems and the users as well as correcting errors that have been reported after deployment.
+However, practical use shows that the environment in which these systems run does, in fact, change.
+These changes include, but are not limited to, modifications to the expected behavior or additions to it, reconfiguration of parameters related to the communication with other systems or the users, as well as correcting errors, particularly security related issues, that have been reported after deployment and roll-out.
 In almost all cases, the requirements can be accomplished by changing the firmware and do not need any modification to the hardware.
 For updating the firmware on a system being deployed, the system must provide an interface for altering the firmware.
 In addition, such an interface should provide mechanisms to check which firmware is currently installed and which configuration parameters are used.
@@ -21,5 +21,6 @@ If a system is already able to communicate over a network interface, this can be
 By reusing the existing communication channels, the dedicated update interface can be omitted which leads to smaller packaging and reduces production cost.
 It also decreases the maintenance cost drastically, because updates can be triggered remotely.
 
-\textit{OTA} updates enables administrators to apply automation methods on the update process allowing to roll out updates in a controlled fashion. I.e. updates can be done on testing devices first, followed by security-critical deployments and subordinate ones can be delayed to times where the device is not utilized.
-Information about the update status provided by the devices allows administrators to apply monitoring techniques ensuring all updates are installed and devices are in the desired state.
+\textit{OTA} updates enable administrators to apply automation methods on the update process allowing to roll out new releases and fixes in a controlled fashion.
+As an example, updates can be done on test-devices first, followed by security-critical deployments and subordinate ones can be delayed to times when the device is not utilized.
+Further, a feedback channel which provides information about the update status of a devices allows administrators to apply monitoring techniques ensuring all updates are installed and devices are in the desired state.

3-environment.tex

@@ -2,27 +2,20 @@
 
 The research presented in this paper was mainly driven by \textit{Magrathea Laboratories e.V.}\cite{maglab}, the local hackerspace in Fulda, in cooperation with researchers at the department for computer science at Fulda University.
 Requirements were clearly defined by Magrathea Laboratories demands to provide local and remote control over various sensors and actors in the foundations rooms to visitors and members.
-Such components include but are not limited to door sensors, power sockets, temperature sensors, projectors and screens who are all managed by a home-automation controller, which is driven by the software \textit{home-assistant}\cite{HASS}.
+Such components include door sensors, power sockets, temperature sensors, projectors and screens who are all managed by a home-automation controller, which is driven by the software \textit{home-assistant}\cite{HASS}.
 It provides direct control over all existing components using a web UI and allows to define rules and automations on how these components interact.
 
-For the component's hardware, boards based on the \textit{ESP8266} micro-controllers, mostly \textit{ESP-01s} \cite{ESP-01s} boards, are used in combination with self-developed power supplies and use-case specific hardware components.
+For the component's hardware, boards based on the \textit{ESP8266} micro-controller are used.
 These boards feature a small and robust design, achieve very low power consumption and integrate WiFi without requiring any extra components.
 It integrates a Tensilica L106 32-bit micro controller unit (MCU) with a maximum CPU performance of 160 MHz, 64 kB instruction memory and another 96 kB of main memory. 
-According to the manufacturer, it is among the most integrated WiFi-capable chips in the industry.
+According to the manufacturer, the ESP8266 is among the most integrated WiFi-capable chips in the industry.
+While at the beginning of this research, mostly \textit{ESP-01s} \cite{ESP-01s} boards in combination with self-developed power supplies and use-case specific hardware components were deployed, we quickly integrated wireless smart switches offered by Sonoff.
 For these boards, a common software platform referred to as \textit{ESPer} \cite{ESPer} has been developed.
 The software is based on the \textit{Sming} \cite{Sming} library, which in turn is based on the open-source SDK for \textit{ESP8266} and integrates a lot of other software components for easy use.
-To build the software, a \textit{Makefile} \cite{make} is used, which provides a simple way for reproducible builds.
 
-The base topology used is shown in Figure \ref{fig:topology}. 
 For communication with the controller, the \textit{MQTT} \cite{MQTT} protocol is used.
 It provides a lightweight messaging mechanism implementing the publish-subscribe pattern that allows devices to listen for commands and publish their current state to the controller and other interested parties.
 The controller software has out-of-the-box support for this protocol, which allows easy integration of all different device types using the same patterns.
 
-\begin{figure}[htbp]
-\centering\fbox{\includegraphics[width=0.9\linewidth]{topology.pdf}}
-\caption{The base network topology.}
-\label{fig:topology}
-\end{figure}
-
 The components all share the same configuration in regard to the network access and the controller to communicate with.
 The configuration is provided during build time, which eschews the need for a configuration interface and reduces the management overhead, thus minimizing security leaks.

4-requirements.tex

@@ -1,32 +1,30 @@
 \section{Requirements}
 
-The following requirements are defined as global project goals and have been refined during the work on the project multiple times.
+For the implementation of an OTA update mechanism, the following requirements were defined.
 
 \begin{itemize}
-\item The systems should be able to perform updates on the release of new software without administrative interaction.
-If a new version of the firmware is published, it should be prepared automatically for installation to the target devices.
-All these devices should then download and install the new software version and start using it subsequently, if no errors have occurred during the process.
+\item The systems should be able to perform updates on the release of new software without manual interaction.
+If a new firmware version is published, it should be prepared automatically for installation on the target devices.
+All these devices should then fetch and install the new software version and start using it subsequently, if no errors have occurred during the update.
 
-\item To ensure minimal maintenance effort, the update process should be insusceptible to errors as most as possible.
-Even if the installation of an update fails in the middle of reprogramming the controller, the system should continue to work fully functional immediately and after a reboot.
+\item To ensure minimal maintenance effort, the update process should be insusceptible to errors as much as possible.
+Even if the installation of an update fails in the middle of reprogramming the device, the system should continue to work fully functional immediately and after reboot.
 
-\item Downloading the updated firmware should be done over the WiFi interface using the same network connection as used during normal operation.
+\item Firmware downloads should be performed over the same WiFi connection as used during normal operation.
 Fetching the firmware should be done side-by-side with operational traffic.
 
 \item The update process can happen over any untrusted wireless network or Internet connection without being vulnerable to attackers.
 To prevent possible attackers from injecting malicious software into the embedded devices, a cryptographic signature mechanism must be implemented.
 New firmware only gets accepted by the device, if the cryptographic signature of the downloaded firmware image can be verified.
 
-\item Reducing network load and aiming for the maximum possible device uptime is critical.
-Therefore, the update process should only be done if a new version is available.
-In contrast, the release of a new update should be rolled out to all devices as fast as possible.
-While checking for available updates and downloading such an update, the device should continue to work as usual.
+\item To reduce network load and aim for the maximum possible uptime of the device, the update process should only be done if a new firmware version is available.
+In contrast, on the release of new firmware, the roll-out to all devices should be performed as fast as possible.
+%While checking for available updates and downloading such an update, the device should continue to work as usual.
 
 \item For easy maintenance and monitoring, each device should provide detailed information about the currently installed firmware version and other details relevant for the update process.
 
 \item Devices are categorized by types.
 Each type runs the same software and therefore provides the same functionality.
 As the device type is hardly coupled to the hardware and the software interacts with it on a specific way, the update process must ensure that the correct firmware is used while reprogramming.
-The according device type is provided as a string through a global constant at compile time and it must never be changed during operation.
 
 \end{itemize}

5-1-update_mechanism.tex

@@ -26,11 +26,13 @@ This allows faster roll-outs of updates and finer control for manual maintenance
 
 \subsubsection{Reprogramming the device}
 
-As the binary to download and flash possibly exceeds the size of free memory heap space, the received data must be written to the flash directly.
-In contrasts, executing the code from the memory mapped flash while writing the same area with the downloaded update leads to errors, as the executed code changes immediately to the updated one.
-To avoid this, the flash is split into half to contain two firmware ROMs with different versions, one being executed and one which is being downloaded.
-This standby firmware also acts as a safety mechanism if the download fails or is interrupted as the previous version stays intact and can still be used.
-In case of an error the old firmware is kept unchanged and will be used until the successful download of a newer firmware succeeds.
+As the \textit{ESP-01s} is only equipped with 1 MB of flash, this means that the whole memory is mapped to a contiguous address space.
+Therefore, the second ROM can not be re-mapped to have the same start address as the first ROM.
+While the firmware is executed without any dynamic linking mechanism and the chip does not support position independent code, the addresses used in the ROMs are dependent to the offset at which the firmware is stored.
+This arises the need for building two firmware binaries, one for each target location.
+To do so, a linker script for each of the two ROM slots was created, which is used to create two variations of the same firmware, only differing in ROM placement.
+The two resulting firmware binary files are both provided for download via \textit{HTTP 1.1} - which one to download depends on the target ROM slot and is selected by the device during the update process.
+Listing~\ref{lst:linker_script} shows the only difference between the two linker scripts, where \texttt{\$\{SLOT\}} must be replaced with the slot number according to the current build.
 
 \begin{lstlisting}[language=,
                    caption={Linker script to build firmware for two ROM slots.},
@@ -44,28 +46,12 @@ irom0_0_seg :
   len = ( 1M / 2 - 0x2010 )// Half ROM size excl. bootloader
 \end{lstlisting}
 
-\begin{figure}[htbp]
-\centering\includegraphics[scale=0.6]{flash_layout.pdf}
-\caption{The flash layout used for two ROMs.}
-\label{fig:memory_layout}
-\end{figure}
-
-Microcontroller boards based on the \textit{ESP8266} MCU are mostly following the same layout: the MCU is attached to a flash chip which contains the bootloader, firmware and other application data.
-The memory mapping mechanism of the MCU allows only a single page of 1 MB of flash to be mapped at the same time\cite{ESP8266_Memory_Map} and the selected range must be aligned to 1 MB blocks.
-As the \textit{ESP-01s} is only equipped with 1 MB of flash, this means that the whole memory is mapped to a contiguous address space.
-Therefore, the second ROM can not be re-mapped to have the same start address as the first ROM.
-While the firmware is executed without any dynamic linking mechanism and the chip does not support position independent code, the addresses used in the ROMs are dependent to the offset at which the firmware is stored.
-This arises the need for building two firmware binaries, one for each target location.
-To do so, a linker script for each of the two ROM slots was created, which is used to create two variations of the same firmware, only differing in ROM placement.
-The two resulting firmware binary files are both provided for download via \textit{HTTP 1.1} - which one to download depends on the target ROM slot and is selected by the device during the update process.
-Listing~\ref{lst:linker_script} shows the only difference between the two linker scripts, where \texttt{\$\{SLOT\}} must be replaced with the slot number according to the current build.
 
-In addition to the two ROMs, the flash must provide room for the bootloader and its configuration.
 \textit{rBoot}\cite{rBoot} has been choosen as it is integrated within the \textit{Sming} framework and allows to boot to multiple ROMs.
 For configuration, an \textit{rBoot} specific structure is placed in the flash at a well-known location directly after the space reserved for the bootloader code.
 This structure contains, among other things, the target offsets for all known ROMs and the number of the ROM to boot from on next reboot.
 
-The full memory layout of this approach is shown in Figure~\ref{fig:memory_layout}.
+%The full memory layout of this approach is shown in Figure~\ref{fig:memory_layout}.
 To calculate the origin of application data for each slot, the available memory of 1 MB is split in half and an offset of the size of the bootloader code and its configuration (0x2000 bytes) is added.
 For alignment and easy debugging, the second block is also shifted by the same amount ob bytes as the first block.
 The unused gap of 8192 bytes is used by some applications to store data which can persist over application updates.
@@ -95,8 +81,3 @@ Listing~\ref{lst:choosing_rom} shows the algorithm used to determine the downloa
 
 After the download of a new ROM has been finished successfully, the bootloader configuration is altered to boot to the new ROM slot and the device is rebooted.
 
-
-\subsubsection{Publish device information}
-For monitoring and maintenance purposes, each device publishes a set of information to a well-known \textit{MQTT} topic after connecting to the network.
-Beside already existing dates like device type, chip and flash ID, the information block has been extended with details about the bootloader, SDK and firmware version as well as relevant details from the bootloader configuration, like the currently booted ROM slot and the default ROM slot to boot from.
-This allows administrators to find devices with outdated bootloaders and helps to find missing and failed updates.

5-2-multidevice_build_structure.tex

@@ -1,24 +1,5 @@
 \subsection{Multi-Device build infrastructure}
 
-The firmware for all \textit{ESP8266} based devices in the hackerspace are all based on the same framework.
-\textit{Sming} provides the base library for this framework.
-In addition, components and functionality shared by all devices has been identified and are providing a framework for the existing and possible further devices.
-This framework provides a functional base for all devices and allows to reuse code providing functionality which is common in multiple devices.
-The framework also includes a build system, which allows to configure some basic parameters for all devices.
-Including, but not limited to, the Wi-Fi access parameters, the \textit{MQTT} connection settings and the updater URLs.
-By sharing the same code, all devices ensure to have a common behavior when it comes to reporting the device status or interacting with the home-automation controller.
-This eases configuration and allows to collect information about all devices at a central location.
-
-Each device firmware exists as a separate project and includes a link to the framework.
-As development on these devices happens in cycles, older projects are missing updates of the framework and therefor do not benefit from newly added features or fixed problems.
-Updating the framework version and rebuilding the firmware would often result in an easy gain of these benefits, but requires manual interaction.
-More problems will arise if the application programming interface (API) of the framework changes.
-In this situation, the device firmware must be updated to use the changed API, which can be an unpleasant and complex task and leads to higher latency for firmware updates.
-
-To prevent these problems the device firmware of all devices in the hackerspace is now integrated with the framework into a larger project.
-By doing so, each device specific code is always linked to the latest version of the framework.
-Device specific code is now organized as a folder for each device type.
-The build system has been modified to scan for all device specific folders and call the original build process for each of them.
 
 
 \subsubsection{Framework integration}

5-3-automatic-deployment.tex

@@ -1,9 +1,9 @@
 \subsection{Automatic deployment and roll-out}
 
-The source code of the \textit{ESPer} project is published into a \textit{GIT} source code repository which is provided by the hackerspace.
-To avoid interferences between different build environments on developers computers and roll out new versions as early as possible, the code has been integrated into a continuous integration (CI) system.
-The CI, which is based on \textit{drone}\cite{drone} and provided as part of the hackerspace infrastructure, allows to execute commands on each version published into the \textit{GIT} repository.
-Therefore a \textit{drone} configuration file as shown in Listing~\ref{lst:drone} has been added to the source code as \texttt{.drone.yml}.
+%The source code of the \textit{ESPer} project is published into a \textit{GIT} source code repository which is provided by the hackerspace.
+%To avoid interferences between different build environments on developers computers and roll out new versions as early as possible, the code has been integrated into a continuous integration (CI) system.
+%The CI, which is based on \textit{drone}\cite{drone} and provided as part of the hackerspace infrastructure, allows to execute commands on each version published into the \textit{GIT} repository.
+%Therefore a \textit{drone} configuration file as shown in Listing~\ref{lst:drone} has been added to the source code as \texttt{.drone.yml}.
 
 \begin{sloppypar}
 As shown in the configuration Snippet, the build environment includes some special settings.

esper-ota.tex

@@ -465,6 +465,7 @@ Secure Updates, Over the Air, ESP8266.
 \input{2-related-work}
 \input{3-environment}
 \input{4-requirements}
+\input{foo}
 \input{5-implementation}
 \input{6-conclusion}
 

foo.tex

@@ -0,0 +1,78 @@
+\section{Concept for implementing OTA updates}
+
+Implementing \textit{OTA} updates under the given requirements involves three different components, which interact closely.
+
+
+
+
+
+
+
+\subsection{flash layout and concept}
+Microcontroller boards based on the \textit{ESP8266} MCU are mostly following the same layout: the MCU is attached to a flash chip which contains the bootloader, firmware and other application data.
+The memory mapping mechanism of the MCU allows only a single page of 1 MB of flash to be mapped at the same time \cite{ESP8266_Memory_Map} and the selected range must be aligned to 1 MB blocks.
+
+\begin{figure}[htbp]
+\centering\includegraphics[scale=0.6]{flash_layout.pdf}
+\caption{The flash layout used for two ROMs.}
+\label{fig:memory_layout}
+\end{figure}
+
+As the binary to download and flash possibly exceeds the size of free memory heap space, the received data must be written to the flash directly.
+In contrasts, executing the code from the memory mapped flash while writing the same area with the downloaded update leads to errors, as the executed code changes immediately to the updated one.
+To avoid this, we chose the memory layout shown in Figure~\ref{fig:memory_layout}.
+The flash is split into half to contain two firmware ROMs with different versions, one being executed and one which is being downloaded.
+This standby firmware also acts as a safety mechanism if the download fails or is interrupted as the previous version stays intact and can still be used.
+In case of an error the old firmware is kept unchanged and will be used until the successful download of a newer firmware succeeds.
+
+In addition to the two firmware ROMs, the flash must provide room for the bootloader and its configuration.
+
+
+\subsection{Common framework and Multidevice support}
+The firmware for all \textit{ESP8266} based devices in the hackerspace are all based on the same framework.
+\textit{Sming} provides the base library for this framework.
+In addition, components and functionality shared by all devices has been identified and are providing a framework for the existing and possible further devices.
+This framework provides a functional base for all devices and allows to reuse code providing functionality which is common in multiple devices.
+The framework also includes a build system, which allows to configure some basic parameters for all devices.
+Including, but not limited to, the Wi-Fi access parameters, the \textit{MQTT} connection settings and the updater URLs.
+By sharing the same code, all devices ensure to have a common behavior when it comes to reporting the device status or interacting with the home-automation controller.
+This eases configuration and allows to collect information about all devices at a central location.
+
+Each device firmware exists as a separate project and includes a link to the framework.
+As development on these devices happens in cycles, older projects are missing updates of the framework and therefor do not benefit from newly added features or fixed problems.
+Updating the framework version and rebuilding the firmware would often result in an easy gain of these benefits, but requires manual interaction.
+More problems will arise if the application programming interface (API) of the framework changes.
+In this situation, the device firmware must be updated to use the changed API, which can be an unpleasant and complex task and leads to higher latency for firmware updates.
+
+To prevent these problems the device firmware of all devices in the hackerspace is now integrated with the framework into a larger project.
+By doing so, each device specific code is always linked to the latest version of the framework.
+Device specific code is now organized as a folder for each device type.
+The build system has been modified to scan for all device specific folders and call the original build process for each of them.
+
+To build the software, a \textit{Makefile} \cite{make} is used, which provides a simple way for reproducible builds.
+
+The according device type is provided as a string through a global constant at compile time and it must never be changed during operation.
+
+
+\subsection{Automatic deployment process}
+The source code of the \textit{ESPer} project is published into a \textit{GIT} source code repository which is provided by the hackerspace.
+To avoid interferences between different build environments on developers computers and roll out new versions as early as possible, the code has been integrated into a continuous integration (CI) system.
+The CI, which is based on \textit{drone}\cite{drone} and provided as part of the hackerspace infrastructure, allows to execute commands on each version published into the \textit{GIT} repository.
+Therefore a \textit{drone} configuration file as shown in Listing~\ref{lst:drone} has been added to the source code as \texttt{.drone.yml}.
+
+
+The base topology used is shown in Figure \ref{fig:topology}. 
+\begin{figure}[htbp]
+\centering\fbox{\includegraphics[width=.98\linewidth]{topology.pdf}}
+\caption{The base network topology.}
+\label{fig:topology}
+\end{figure}
+
+
+
+\subsection{Publish device information}
+For monitoring and maintenance purposes, each device publishes a set of information to a well-known \textit{MQTT} topic after connecting to the network.
+Beside already existing dates like device type, chip and flash ID, the information block has been extended with details about the bootloader, SDK and firmware version as well as relevant details from the bootloader configuration, like the currently booted ROM slot and the default ROM slot to boot from.
+This allows administrators to find devices with outdated bootloaders and helps to find missing and failed updates.
+
+