path: root/docs/formal/main.tex

\documentclass[parskip=half]{scrartcl}

\usepackage[T1]{fontenc}
%\usepackage{helvet}
\usepackage{lmodern}
\usepackage[utf8]{inputenc}
\usepackage[ngerman]{babel}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage[left=3cm,right=3cm,top=3cm,bottom=3cm]{geometry}
\usepackage{array}
\usepackage{pgfplots}
\usepackage{graphicx}
\usepackage{hyperref}
\usepackage{glossaries}
\graphicspath{ {./images/} }	

\renewcommand{\familydefault}{\sfdefault}

\newcommand{\Author}{Jan Drögehoff}
\author{\Author}
	
\hypersetup{
	colorlinks=true,
	linkcolor=black,
	urlcolor=blue,
	pdftitle={ShelSP Dokumentation},
	pdfauthor={\Author},
}

\pgfplotsset{compat=1.18}

\makeglossaries

\newglossaryentry{mdns}
{
    name=Multicast DNS (mDNS),
    description={Multicast DNS ist ein verfahren mit dem Domains zu Geräten im Gleichen Netzwerk ohne einen DNS Server bekannt gegeben und aufgelöst werden können}
}

\newglossaryentry{kicad}
{
    name=KiCad,
    description={Open-Source-Software-Suite für elektronische Schaltungen und zum Platinendesign \url{https://www.kicad.org/}}
}

\newglossaryentry{esp}
{
    name=ESP32-WROOM-32,
    description={
    		Das erste Module der ESP32 Familie des Herstellers Espressif Systems.\\
    		\href{https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf}{Datenblatt}
    }
}

\newglossaryentry{cp2102}
{
    name=CP2102,
    description={
    		Ein Chip der die Kommunikation zwischen eines USB Hosts und einer UART schnittstelle ermöglicht\\
    		\href{https://www.silabs.com/documents/public/data-sheets/CP2102-9.pdf}{Datenblatt}	
    }
}

\newglossaryentry{llc}
{
	name=Logic Level Converter,
	description={
		Ein Chip oder eine Sammlung von Chips die eine Spannung zu einer anderen Referenz Spannung umwandelt. \\
		Wird für Transistor zu Transistor Logik benötigt da nicht alle Komponente mit der gleichen Spannung arbeiten
	}
}

\newglossaryentry{mongoose}
{
	name=Mongoose,
	description={
		Mongoose ist eine Plattformübergreifende Webserver Bibliothek die sich Speziell für Mikrocntroller spezialisiert ist.\\
		\url{https://mongoose.ws/}
	}
}

\newglossaryentry{ams1117}
{
	name=AMS1117,
	description={
		Ein Familie von Abwärtswandlern die ein Strom Signal in ein schwächeres Strom umwandeln. \\
		\href{http://www.advanced-monolithic.com/pdf/ds1117.pdf}{Datenblatt}
	}
}

\begin{document}
\begin{titlepage}
\begin{center}
%\Large{Abschlussprüfung \pruefungstermin}\\[3ex]

%\Large{\ausbildungsberuf}\\
%\LARGE{\betreff}\\[4ex]

\huge{\textbf{Integration eines Mikrocontrollers zur Erweiterung der Automatisierungsmöglichkeiten im Shelly
Ecosystem}}\\[1.5ex]
%\Large{\textbf{\untertitel}}\\[4ex]

\normalsize
\vspace{1.5cm}
%%Abgabetermin: abgabeOrts, den abgabeTermin\\[3em]
\textbf{Prüfungsbewerber:}\\
\Author\\
Scherlebecker Straße 300a\\
45701 Herten\\
Prüfling-Nr: 30070\\[5ex]

%\includegraphics[scale=0.4]{\betriebLogo}\\[2ex]1
\textbf{Ausbildungsbetrieb:}\\
DATATRUSTEE GmbH\\
Josef-Haumann-Str. 7a\\
44866 Bochum\\[5em]
\end{center}

\end{titlepage}

\tableofcontents
\pagebreak

% We want links to be noticable
\hypersetup{
	linkcolor=blue,
}

\section{Planung}
\subsection{Umfeld}

Das Projekt wird im Büro der DataTrustee GmbH durchgeführt für die infraTest Digital Solutions durchgeführt.

Für die Entwicklung der Firmware wird der Sublime Text Editor benutzt.

Der Schaltplan und das Platinen design werden in \gls{kicad} angefertigt.

\subsection{Anforderungen}

Wir haben die Anforderung, eine digitale Anbindung an unsere bestehenden Produkte zu entwickeln, um die Steuerung zu erleichtern und die Bedürfnisse unserer Kunden zu erfüllen.
Für die umsetzung wird ein \gls{esp} verwendet um ein Relais zu schalten mit welchen wir den Physischen schalter ersetzen können.

\subsection{Begründung}
infraTest Digital Solutions vertreibt derzeit Messgeräte mit interner Elektronik, die eine manuelle Konfiguration vor Ort erfordern. Aufgrund zunehmender Standortferne der Kunden wünschen sie sich jedoch die Möglichkeit, die Geräte aus der Distanz zu konfigurieren und einzuschalten.

Die Kunden möchten die Effizienz steigern und Kosten sparen, indem sie die Geräte fernsteuern können. Dies würde auch die Zuverlässigkeit und Genauigkeit der Messgeräte verbessern und eine nahtlose Integration in verschiedene Arbeitsumgebungen ermöglichen.

Wir arbeiten daran, diese Anforderungen zu erfüllen, indem wir eine Prototypen entwicklen womit die fernsteuerung realisiert werde kann, um die Kundenzufriedenheit.
\pagebreak

\subsection{Schnittstellen}

Zur Kompatibilität mit der Shelly IoT API werden die folgenden Schnittstellen benötigt:
Die Shelly IoT API Kompatibilität benötigt:
\begin{itemize}
	\item WiFi Access-Point zur erstmaligen Konfiguration mit den folgenden Einstellungen:
	\begin{itemize}
		\item SSID mit Gerät Typ und MAC Adresse
		\item Kein Passwort
		\item Statische IP Addresse 192.168.33.1 für das Gerät
		\item DHCP Server für zusätzliche teilnehmer
	\end{itemize}

	\item \gls{mdns} bekannt gebung zur Erkennung mit den folgenden Inhalten:
	\begin{itemize}
		\item Erkennbarkeit im Netzwerk
		\item Firmware Version
		\item Processor Architecture
		\item Geräte Identifizierung via Gerät Typ und MAC Addresse
	\end{itemize}

	\item HTTP Routen zum Abfragen und Einstellen von:
	\begin{itemize}
		\item Relay
		\item WiFi Einstellungen
		\item Cloud Integration
	\end{itemize}
\end{itemize}

\subsection{Zeitplanung}
Für das Projekt gibt es die folgende Zeitplanung 

\begin{tabular}{ | l | r | } 
  \hline

  Analyse& 3 \\
  Konzept& 10 \\
  Realiserung& 34 \\
  Tests& 8 \\
  Dokumentation& 13 \\
  Fazit& 7 \\
  Puffer& 5 \\
  \hline
  \hline
 
  \textbf{Gesamt}& 80 Stunden \\
  \hline
\end{tabular}

\pagebreak

\subsection{Ist Analyze}	

Derzeit verkaufen wir Messgeräte die intern vor-konfektionierte Elektronik besitzen und von uns nur Elektronisch verkabelt werden damit die Nutzung für den End-Nutzer vereinfacht wird.


\subsection{Kosten-Nutzen Analyse}
Mit der Kosten-Nutzen Analyse ermitteln wir die Wirtschaftlichkeit des Projektes für die Firma.
Das Projekt kommt aus Nachfragen von Kunden, ist aber kein direktes Kunden Projekt.

\begin{tabular}{ | l | r | } 
  \hline
  Projektstunden& 80\\
  Auszubildener Stundenlohn& 35,00 €\\
  \hline
  \hline
  Arbeitslohn& 2.800,00 €\\
  \hline
\end{tabular}

Der berechnete Arbeitslohn bezieht sich auf Durchschnittliche Werte und ist nicht unbedingt Personen bezogen.

\begin{tabular}{ | l | r | } 
  \hline
  Lohn& 2.800,00 €\\
  Hardware Pauschale& 100,00 €\\
  Ressourcen-Pauschale& 100,00 €\\
  \hline
  \hline
  Projektkosten& 3.000,00 €\\
  \hline
\end{tabular}

Mit dem Projekt würde sich ein möglicher Kunde die mehrfache Anfahrt zu einem Ort sparen in dem des Gerät Ferngesteuert werden kann.

Da wir nicht genau wissen können wie der Kunden anfährt vermuten wir die Nutzung eines PKWs mit durchschnittlichen Verbrauch sowie durchschnittliche Spritkosten und eine Entfernung die der Realität entspricht.
 
\begin{tabular}{ | l | r | } 
  \hline
  Entfernung& 160 km\\
  Spritkosten pro Liter& 1,90 €\\
  Verbrauch / 100km& 7 l\\
  \hline
  \hline
  Anfahrkosten& 21.28 €\\
  \hline
\end{tabular}

\begin{tikzpicture}
\begin{axis}[
    title={Wirtschaftsrechnung},
    xlabel={Anfahrten},
    ylabel={Kosten},
    xmin=0, xmax=200,
    ymin=0, ymax=5000,
    xtick={0,50,100,150,200,250,300},
    ytick={0,500,1000,1500,2000,2500,3000,3500,4000,4500},
    legend pos=north west,
    ymajorgrids=true,
    grid style=dashed,
]

\addplot [
    domain=0:200, 
    samples=100, 
    color=blue,
    ]
    {x * 21.28};
\addlegendentry{Anfahrkosten}

\addplot [
	domain=0:200,
    samples=12, 
    color=red,
    ]
    {3000};
\addlegendentry{Projektkosten}

\end{axis}
\end{tikzpicture}

Das Projekt würde nach \textit{141} Anfahrten billiger sein als die Anfahrkosten.
Bei Kunden die eine Großzahl an Geräten verwenden würde sich das Projekt schnell lohnen.

\subsection{Nicht Monitäre Vorteile}
Eine Digital Anbindung würde Automatisierung Möglichkeiten erzeugen wo ein Messsensor zu bestimmten Bedingungen eingeschaltet werden kann.

\pagebreak

\section{Konzept}
\subsection{Soll-Konzept}
Für ein Soll-Konzept müssen verschiedene Eigenschaften des Projektes entschieden werden.

Einige Elemente wurden schon im Projektantrag entscheiden, wie zum Beispiel die Auswahl von C++ für die Programmiersprache und den \gls{esp} für den Mikrocntroller.
Diese Entscheidungen werden trotzdem noch einmal übergangen um herauszufinden ob es nicht bessere Alternativen gäbe.

\subsubsection{Programmiersprache}

Für Embedded Software Projekte eignen sich meist Kompilierte Sprachen da diese Quellcode in effizienten Maschinen Code konvertieren und damit Speicherbedarf und Rechnenleistung gespart werden können.
Die Sprachen die zur Wahl stehen sind:
\begin{itemize}
	\item C
	\item C++
	\item Rust
	\item Zig
\end{itemize}

\paragraph{C}
C biete sich am besten an da es Offiziell vom Hersteller Unterstützt wird

\paragraph{C++}
Wie C werden Offizielle Compiler angeboten dazu bietet C++ eine umfangreiche Standardbibliothek sowie Kompatibilität mit C-Bibliotheken, wodurch das Projekt leicht erweitert und angepasst werden kann.

\paragraph{Rust}
Rust ist eine LLVM basierte Programmiersprache und LLVM hat derzeit keine Unterstützung für die Xtensa Architektur des ESP32.
Die Community arbeitet daran Rust für diese Architektur bereitzustellen, jedoch gibt es noch viel was erarbeitet werden muss.

\paragraph{Zig}
Zig ist eine relative neue Programmier Sprache mit noch keinen Stabilen Versionen.
Sie ist zwar nicht an LLVM gebunden, hat derzeit aber noch keine unterstützung für die ESP32 Architektur \\

Erstaunlicher weiße gibt es auch eine beliebte interpretierte Programmiersprache für den ESP32: \textbf{Micropython}

Micropython hat jedoch den Nachteil dass das Programm während der Laufzeit interpretiert werden muss und somit viel langsamer ist als Kompilierte alternative.
Dazu bring die Standardbibliothek nicht viele Funktionalitäten die man vom Hersteller kriegen würden.

Sommit fällt die entscheidung weiterhin auf \textbf{C++}.

\subsection{Mikrocntroller}

In der Mikrocontroller Industrie gibt es viele zur Auswahl, am Ende sind die folgenden Chips in die Engere Auswahl gekommen:

\begin{itemize}
	\item ESP32
	\item ESP8266
	\item RP2040
\end{itemize}

Bei der Auswahl war es wichtig einen Mikrocontroller zu verwenden die in einem praktisch Modul Formfaktor vorhanden sind.
Die eigentlichen Integrierten Chips brauchen meist sehr genaue Anforderungen an passiven Komponenten.

\paragraph{ESP32}
Die ESP32 Familie von Mikrocontrollern ist weit beliebt durch ihre Performanz sowie ihr Kleiner Form Faktor und Netzwerk Fähigkeiten, sei es WiFi, Bluetooth oder sogar Zigbee.
Der Mikrocontroller selbst ist meist als sogenannter System on a Chip, Modul und als Entwicklung Einheit vorhanden.

\paragraph{ESP8266}
Älterer Chipsatz welcher auch Netzwerk fähig ist, wurde jedoch Funktional von der ESP32 Familie ersetzt.

\paragraph{RP2040}
Der RP2040 ist ein neuer AMD basierter Mikrocontroller von der Raspberry Pi Foundation.
Sehr beliebt in Hobby Projekten und sehr Kosten Günstig, je 1€ pro Chip, ist jedoch nur als Entwickler Platine und als System on a Chip verfügbar.
Wifi und Bluetooth müssten extern bei der Platinen Entwicklung angebunden werden.

Am Ende hat sich der \textbf{EP32} war der ESP32 die beste Entscheidung da die Chip Familie gut und weiterhin vom Entwickler sowie von der Community unterstützt wird und durch den Modul Formfaktor bei der Platinen Entwicklung weniger Hindernisse aufbringen wird.

\subsection{Schaltplan}

Der \gls{esp}, braucht eine Aktivspannung on 3.3V und geht von Nominalen 500mA Strom für die Verwendung von WiFi und Bluetooth aus.

Um die Stromversorgung zu vereinfachen wird ein einfacher USB Port verwendet.
Da der USB Standard 5V vorsieht brauchen wir einen Abwärtswandler.
Wir haben uns dabei für den \gls{ams1117} (U5) entschieden welcher eine Spannung von mindestenz 4.7V zu 3.3V umwandelt.
Die Verwendung eines Spannungsteiler ist hier leider nicht möglich, da der USB2.0 Nominal einen Strom von 500mA vorsieht, genug um den Mikrocontroller zu betreiben.

Um zu verhindern, dass die Spannung durch momentare Stromlast gesenkt wird, wird mit 2 Kondesatoren mit jeweils 10uF (C2) und 0.1uF (C1) die Stromversorgungsschiene entkoppelt.
Da bei der entkopplung eine schnelle Reaktionszeit benötigt wird werden Zeramik Kondensatoren benötigt, da diese diese die beste Kapazitive Reaktanz besitzen.

Zur Sicherstellung, das der Mikrocontroller vollständig mit Strom versorgt ist bevor dieser gestartet wird, wird mit einem 1uF Kondensator (C3) der start vezögert.

Da unser Mikrocontroller über eine UART verbindung Programmiert wird haben wir vorgesehen den USB Port für eine Serial Verbindung zu Nutzen, dafür haben wir uns für die \gls{cp2102} USB-zu-UART Brücke (U2) entschieden.
Dieser IC unterstützt eine direkte Anbindung an USB und besitzt Treiber für Windows, Linux, MacOS und Android.
Die Anbindung der Pins folgt UART, dabei wird der DTR und RTS pin zum einschalten des Download modes und zum neu starten verwendet damit das Gerät über USB Autonom Programmiert werden kann.


\includegraphics[scale=0.75]{schematic.png}
\\

\subsection{Software}
Die Entwicklung für den \gls{esp} wurde mit der Offiziellen \href{https://docs.espressif.com/projects/esp-idf/en/stable/esp32/index.html}{ESP-IDF} Toolchain durchgeführt.
Diese Unterstützt alle Hardware Komponente direkt und kommt mit vielen nützlichen Bibliotheken inkludiert welche in diesem Projekt verwendet werden, zum Beispiel ein \href{https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/protocols/esp_http_server.html?highlight=http}{HTTP Server}.

Ehemalig war mDNS Unterstützung teil der Entwicklungsumgebung, wurde aber später von Espressif als eigene Komponente abgetrennt.
Da die Inklusion dieser Komponente sehr einfach ist werden wir diese für das Projekt benutzen.

\pagebreak

\section{Realisierung}
\subsection{Hardware}
Der Prototyp wurde auf einem Breadboard aufgebaut, wobei vorgefertigte Breakout-Boards genutzt wurden, um Kosten bei der Entwicklung einzusparen. Ein wesentlicher Unterschied zwischen dem Schaltplan und dem Platinen-Design besteht darin, dass im Breadboard-Design ein \gls{llc} zur Unterstützung der seriellen Verbindung mit anderen Chips verwendet wurde. Da der \gls{cp2102} Chip mit Spannungen von 3,3 und 5V arbeiten kann, wurde dies nicht weiter benötigt. Für den \gls{esp} wurde aufgrund des Mangels an einem vorgefertigten Breakout-Board ein eigenes Board entworfen und produziert.

\begin{center}
\includegraphics[scale=0.20]{esp_breakout_bare.jpg}
\includegraphics[scale=0.20]{esp_breakout.jpg} \\
\vspace{0.5cm}
\includegraphics[scale=0.1]{breadboard.jpg} \\
\end{center}
\newpage

\subsubsection{Platine}

Für den Prototypen gibt es ein vollständiges Platinen design mit jeweils den gleichen Komponent wie sie auf dem Breadboard zu finden sind.

\begin{center}
\includegraphics[scale=0.27]{pcb_layout.png}
%\includegraphics[scale=0.25]{pcb_3d_blank.jpg}
\includegraphics[scale=0.17]{pcb_3d_models.jpg}
\end{center}
%\pagebreak
%\includegraphics[scale=0.25]{pcb_3d_perspective.jpg}

\subsection{Software}
Die Software wurde vollständig in prozeduralem C++ verfasst, da die ESP-IDF Komponenten sich mehr für prozeduralem Strukturen eignen.

Für die Implementierung wurde die Logik in die folgende Komponente unterteilt:
\begin{itemize}
	\item HTTP Server und Routen
	\item Netzwerk Logik
	\item Relay Logik
	\item Einstellungen
\end{itemize}
Somit wird sichergestellt das Änderungen an einzelnen Komponenten keinen Indirekten Einfluss auf andere haben kann.

\subsubsection{HTTP Server und Routen}
Als HTTP Server benutzen wir die inkludierte Komponente der ESP-IDF Toolchain.
Diese erlaubt uns beliebig viele Routen zu registrieren die wir dann verarbeiten können.

Routen wurden in einen Unterordner ausgelagert wo die Methoden eines Hauptpfad in eine Datei implementiert werden.

So werden z.B. \textit{/settings} und \textit{/settings/sta} von \textit{settings.cpp} implementiert.

\subsubsection{Netzwerk}
Für die WiFi Nutzung wird die die \href{https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/network/esp_netif.html}{ESP-NETIF} Komponente Verwendet.
Diese erlaubt uns verfügbare Netzwerk Hardware anzusteuern und über Generische Methoden anfragen zu versenden.

Für \gls{mdns} wird die die \href{https://components.espressif.com/components/espressif/mdns}{mdns  Komponente} von Espressif verwendet welche sich direkt mit netif integriert.

\subsubsection{Relais}
Die Relay Komponente beinhaltet Methoden womit externe Komponente den Status des Relais abfragen und ändern können.

\subsubsection{Einstellungen}
Die Einstellung beinhaltet Methoden zum einstellen und abfragen von Konfigurationen wie zum Beispiel die WiFi Konfiguration.


\pagebreak
\section{Testphase}

\subsection{Blackbox Test}

Mit Blackbox Tests Prüfen wie die Funktionalität des Web Servers sowie der jeweiligen Routen und deren Verhalten.
Im gegensatz zu einem Whitebox tests sind Implementierungs Details irrelevant solange das Geräte richtig auf Anfragen reagiert.

Um dies zu Testen haben wir 2 Programme laufen lassen:

\begin{itemize}
	\item Ein Programm das dauerhaft das Relay ausschalten wollte, und überprüft hat ob die Antwort den Status als Aus zurück gegeben hat
	\item Ein Programm das dauerhaft das Relay einschalten wollte, und überprüft hat ob die Antwort den Status als Ein zurück gegeben hat
\end{itemize}

Über 8 Stunden gab es dabei keine Probleme.

\subsection{Stress Test}
Mit Stress Test wird die Belastbarkeit und Leistung des Web Servers überprüft.
Dies ist besonders über längere Zeiträume wichtig um potenzielle Probleme frühzeitig zu ermitteln.

Um das Gerät gründlich zu strapazieren haben wir einen Test aufgebaut wobei das Gerät von 3 Endgeräten über 24 Stunden dauerhaft angefragt wurde und Relais umgeschalten.

Bei den Test ist es zu keinen Ausfällen gekommen, jedoch hat sich gezeigt das der HTTP Server inkludiert in ESP-IDF sich nicht sehr gut belasten lässt. 

\pagebreak

\section{Dokumentation}
\subsection{Erstellung}
Die Software wurde nach dem Prinzip der Selbst-Dokumentierung Entwickelt, so ist der Nutzen jeder Funktion direkt erkennbar oder, wenn dieser zu ungenau ist in der Beschreibung der Funktion.

Um eine Übersicht über die Firmware zu gewährleisten wird Doxygen benutzt um ein HTML und PDF Dokument zu erstellen mit dem man die selbst-dokumentierten Informationen einsehen und direkt mit dem Quellcode vergleichen kann.

\subsection{Kundendokumentation}
Die Kundendokumentation besteht aus einer kleinen Einleitung zur Konfiguration und Bedienung des Gerätes mit Bildern der App zu Hilfestellung.
\\
Der Elektronische Einbau ist in der Kundendokumentation nicht beschrieben, da dies von uns in Geräte vorgefertig wird.
\\ \\
\hyperref[sec:kd]{8.2 Kundendokumentation}
\pagebreak

\section{Fazit}
\subsection{Erkenntnisse}

Wärend der Testphase wurden einige Erkenntnisse gesammelt wie das Projekt in der Zukunft verbessert werden könnte:
\begin{itemize}
	\item Die ESP-IDF HTTP Server Komponente ist nicht für hohe Verfügbarkeit optimiert, so kann es dazu kommen das Anfragen verzögert verarbeitet werden. Ein alternative HTTP Server der sich besser hierfür eignet wäre \gls{mongoose}
\end{itemize}

\subsection{Ausblick}
Das Projekt wurde vollständig umgesetzt und erfüllt die erforderten Anforderungen.
Bei der Entwicklung sind Erkenntnisse aufgekommen die die Belastbarkeit verbessern würde, was man mit der Simplen jedoch Effizienten Struktur der Software leicht umsetzen kann.
\pagebreak

\section{Anhang}

\subsection{Glossar}
\printglossary[title=]
\pagebreak

\setcounter{subsection}{1}
\subsection{Kundendokumentation}
\label{sec:kd}
\input{Kundendokumentation}
\pagebreak

\setcounter{subsection}{2}
\subsection{Sequenzdiagram}
\begin{center}
\includegraphics[scale=0.8]{uml/Sequenzdiagram.png}
\end{center}

\subsection{Aktivitätsdiagram}
\begin{center}
\includegraphics[scale=0.38]{uml/Aktivitätsdiagram.png}
\end{center}

\end{document}