\chapter{User Manual}
\pagestyle{empty}

This appendix chapter includes details on how to use and extend the developed SmartCGMS concept. The project is split into three repositories:

\begin{itemize}
    \item SmartCGMS Embedded Codebase
    \item Build Environments
    \item Build System
\end{itemize}

The SmartCGMS Embedded Codebase repository contains the current modified codebase of SmartCGMS. When the concept is officially adopted by SmartCGMS, this repository will be replaced by the official SmartCGMS repositories \texttt{core} and \texttt{common}. 

The Build Environments repository contains files and directories used to build the SmartCGMS concept for all supported platforms. Each platform has its directory in the root directory of the repository. Each currently supported platform uses CMake to simplify the build process. Each platform provides a \texttt{build} script that generates the compiled binary. Some platforms contain additional \texttt{run} script that uploads the binary to the platform. Directories of low-power supported platforms contain the source code of FreeRTOS and required drivers.

The Build System repository is targeted at GNU/Linux. It contains a Python script to pull the SmartCGMS code and the build environment for a specified platform from the repositories. It also contains the filter preprocessor tool. When executing the Python script, the filter preprocessor tool is used to modify the source code files of filters in the \texttt{input} folder. The repository contains a Dockerfile to build an image that can be used to execute the Python script.
\newpage
\section*{How to Develop a SmartCGMS Concept Application}

The build system and the build environments are targeted at \texttt{GNU/Linux}. It is therefore recommended to use \texttt{GNU/Linux} when building the SmartCGMS concept application.

\subsection*{Toolchains}

The dependencies differ for each platform. The table \ref{tab:tools} presents the required tools and toolchains for each platform. 


\begin{table}[htpb]
  \caption[Required Tools for the SmartCGMS Concept]{Tools required by the SmartCGMS concept}\label{tab:tools}
  \centering
  \begin{tabular}{l l}
    \toprule
     Tool & Required by \\
    \midrule
      Git & The Build System \\
      Docker & The Build System \\
      CMake & All platforms \\
      \acs{espidf} & ESP32 \\
      ARMv6 Cross-compiler & RasperryPi Zero W \\
      Emscripten & \gls{wasm} targeted at the web \\
      \acs{wasi} \acs{sdk} & \gls{wasm} for \acs{wamr} \\
    \bottomrule
  \end{tabular}
\end{table}



\subsection*{Developing Filters}

The SmartCGMS concept supports only the filters from the SmartCGMS entities. To develop a custom application using the SmartCGMS concept, the user must first implement custom filters for their desired platforms. To develop a filter, follow the official \href{https://diabetes.zcu.cz/docs/api/filter}{\color{blue}{SmartCGMS documentation}}. There are four experimental filters provided with the SmartCGMS concept. They are described in the chapter \ref{chapter-implementation}. 

\subsection*{Cloning the Build System Repository}

Once the filters are implemented. The next step in creating the SmartCGMS concept application is to clone the Build System repository. To do so, the user can use the command displayed in listing \ref{lst:gitclone}. The Build System is also provided in the folder \texttt{Aplication\_and\_libraries/Build\_System\_Linux/build\_script}.

\setuxprompt{petrk@pc}{}
\begin{console}{Cloning the Build System repository\label{lst:gitclone}}
`\uxprompt`git clone https://github.com/PetrKocian/SCGMS-Build-System.git
\end{console}

\subsection*{Creating a Folder for a Supported Platform}

The Build System repository contains the filter preprocessor tool and a Python script to create build directories for supported platforms.

The build directory-generating script can be used in the provided Docker image or the local GNU/Linux environment. The dependencies for the build script are defined in the Dockerfile. To use the Docker image, it has to be built first. It can be done by running the \texttt{build\_docker.sh} script or executing directly the command from listing \ref{lst:docker}:  


\setuxprompt{petrk@pc}{}
\begin{console}{Building a Docker image for executing the Python build script \label{lst:docker}}
`\uxprompt`docker build docker -t scgms-builder
\end{console}

After the Docker image is built, the supported platforms can be displayed by executing the \texttt{run\_docker.sh} script without any parameters. To generate a build directory for a desired platform, invoke the script with the name of the platform as the only parameter. The names of the supported platforms are:

\begin{itemize}
    \item esp32
    \item rpizerow
    \item wasm\_emcc
    \item wasm\_wamr
\end{itemize}

The directories for all platforms can be generated at once by providing the parameter \texttt{all} (seen in listing \ref{lst:buildall}).

\setuxprompt{petrk@pc}{}
\begin{console}{Running the Python build script inside using provided Docker script. \label{lst:buildall}}
`\uxprompt`./run_docker.sh all
\end{console}

The Python script \texttt{paths\_to\_toolchains.py} contains the paths to required toolchains used by individual platforms. These paths are used to generate CMake files or shell scripts that are then used by the platforms' build scripts. If the installation location of the toolchains differs for the user, these paths should be edited directly in the script to ensure the correct generation of the toolchain files in the platform build directories.

\begin{verbatim}
    
# PATHS TO TOOLCHAINS
esp_idf_path = "~/esp/esp-idf"
wasi_path = "/opt/wasi-sdk"
emsdk_path = "~/emsdk"
\end{verbatim}

The script also invokes the filter preprocessor. The original filter source code files are taken from the \texttt{input} directory. The filter preprocessor then generates files that are ready for compilation in the platform directory.

\begin{important}
The script does a clean build whenever its invoked - the directory where the platform build files are generated is deleted and then generated again. It is therefore important to copy the generated folder to a different location or rename it, in case it should not be deleted.
\end{important}

\subsubsection*{Alternative Approach without Docker}

The Python build script can be invoked directly. To use it, it is necessary
to install:

\begin{itemize}
    \item Python
    \item GitPython
\end{itemize}

The script can then be called directly. See listing \ref{lst:python}.

\setuxprompt{petrk@pc}{}
\begin{console}{Invokind Python build script directly. \label{lst:python}}
`\uxprompt`python prepare_build.py all
\end{console}

\subsubsection*{Filter Preprocessor}

The filter preprocessor can be used as a standalone application. To preprocess the filters, copy their source code files to \texttt{input} directory where the filter preprocessor executable is located. Then run the \texttt{preprocessor} executable. If the preprocessing is successful, the modified filter files are generated to \texttt{temp} directory. 



\subsection*{Building the SmartCGMS Concept Executable}

Once the build directory for a platform is generated, it should be possible to build an executable for the target platform. Each platform build directory contains a shell script \texttt{build.sh}. If the toolchain paths have been specified correctly in the previous step, the \texttt{build.sh} should compile the SmartCGMS concept executable to a \texttt{build} directory.


\subsection*{Executing the SmartCGMS Concept Application}
\subsubsection*{Raspberry Pi Zero W}

To execute the SmartCGMS concept application on Raspberry Pi Zero W, ensure that the Raspberry Pi has a \href{https://github.com/MartinUbl/KIV-RTOS/tree/master/misc/bootloader}{\color{blue}{SREC bootloader}} on its microSD card. Once the executable is ready, restart the Raspberry Pi Zero W (e.g., unplug and plug back in power) and execute the \texttt{start.sh} script. The script uploads the \texttt{rpiscgms.srec} SREC image to the Raspberry Pi Zero W over UART and then starts listening on UART. The upload is slow - approximately 5 minutes - but it can be uploaded without using a microSD card reader. 

\subsubsection*{ESP32}

To execute the prepared SmartCGMS concept application on the ESP32, the user can use the \texttt{start.sh} shell script. The project uses the \gls{espidf}. To use the \texttt{idf.py} command to interact with the project, the user can \href{https://docs.espressif.com/projects/esp-idf/en/v3.3/get-started-cmake/add-idf_path-to-profile.html}{\color{blue}{export the required variables}} and use the command directly, instead of using the provided shell scripts. The ESP32 application listens on UART for incoming data. A UART sender application is provided in folder \texttt{UART\_Event\_Sender} that periodically sends data to the UART. It can be executed by running the \texttt{run.sh} script.

\subsubsection*{\gls{wasm} for \gls{wamr}}

Once the SmartCGMS concept application for \gls{wamr} is built, it can be executed using the \texttt{iwasm} executable binary. \gls{wamr} provides a guide on how to build the \texttt{iwasm} binary on its \href{https://github.com/bytecodealliance/wasm-micro-runtime/tree/main/product-mini}{\color{blue}{GitHub page}}. The SmartCGMS concept application \gls{wasm} module can then be executed by using the command in listing \ref{lst:iwasm}.


\setuxprompt{petrk@pc}{}
\begin{console}{Executing SmartCGMS concept application \acs{wasm} module using \texttt{iwasm}. \label{lst:iwasm}}
`\uxprompt`./iwasm scgms
\end{console}

\subsection*{GNU/Linux}

To compile the SmartCGMS concept application for GNU/Linux, use the \gls{wasm} for \gls{wamr} environment. Do not use the provided \texttt{build.sh} script, but instead use this series of commands:

\begin{verbatim}
rm -rf build
mkdir build
cd build
cmake ..
make
\end{verbatim}




\subsubsection*{\gls{wasm} for the Web}

To execute the \gls{wasm} module compiled using Emscripten, a demo webpage is provided. To run the compiled \gls{wasm} SmartCGMS module, copy the \texttt{scgms.js}, \texttt{scgms.wasm}, and \texttt{scgms.worker.js} files to the root directory of the \texttt{SCGMS\_Web\_Demo}. To start the server with the demo webpage, use the \texttt{scgms\_server.py} Python script. To be able to start threads in the \gls{wasm} web SmartCGMS demo, \texttt{SharedArrayBuffer} needs to be enabled in the web browser as specified in \href{https://emscripten.org/docs/porting/pthreads.html}{\color{blue}{Emscripten documentation for pthreads}}.


\section*{Introducing New Platforms}

Once a SmartCGMS concept code has been successfully compiled for a new platform, it can be introduced to the build system using the following steps.

\subsubsection*{Create a Build Environment for the Platform}

In the Build Environments repository, create a new folder with the name of the platform. In this folder, all the required drivers, \gls{rtos}, build script, CMake files, and other necessary files are located.

\subsubsection*{Modify winapi\_mapping.cpp}

Using preprocessor macros, specify functions for allocating and freeing memory in the \texttt{winapi\_mapping.cpp} file.

\subsubsection*{Modify prepare\_build.py script}

Add the platform name to \texttt{supported\_archs} variable in the \texttt{prepare\_build.py} script. Create a function to copy the SmartCGMS concept source code and the build environment for the platform to a specified folder. Optionally, add a function to create a script/CMake file to specify required toolchains. Finally, add these functions to the \texttt{main} function in the script behind an \texttt{elif} statement. The functions to create the build directory of the new platform should also be added to the \texttt{elif} statement specifying all platforms.