From fa0c31d9e436a28a9809f1b51eda4e1cb17285f2 Mon Sep 17 00:00:00 2001 From: Gerhard Hoffmann Date: Fri, 2 Jun 2023 14:17:48 +0200 Subject: [PATCH] save for the weekend --- doc/update_ptu.tex | 140 ++++++++++++++++++++++++++++++++------------- 1 file changed, 101 insertions(+), 39 deletions(-) diff --git a/doc/update_ptu.tex b/doc/update_ptu.tex index 08515af..e031dc6 100644 --- a/doc/update_ptu.tex +++ b/doc/update_ptu.tex @@ -2,6 +2,7 @@ \usepackage{euler} \usepackage[english]{babel} \usepackage{lipsum} +\usepackage{multirow} \usepackage[colorlinks=true, urlcolor=blue, linkcolor=red]{hyperref} \newcounter{Chapcounter} \newcommand\showmycounter{\addtocounter{Chapcounter}{1}\themycounter} @@ -19,44 +20,58 @@ \begin{document} \maketitle -\chapter{Introduction} - \section{Motivation} - The two main components of a PSA are - \begin{itemize} - \item PTU software. - \item Device controller (DC) firmware. - \end{itemize} - While the DC firmware is basically the same for each PSA (even for different - customers), the PTU software is highly dependent on customer requirements.\par - Hence, each customer is assigned an own git-repository, which will be loaded - ("cloned") on the PSA when configuring the machine for the first time.\par - Two special tools, the {\bf UpdateController} (a \href{https://doc.qt.io/qt-5/}{Qt} - binary [{\bf \nameref{UpdateTool}}]) and the {\bf UpdateScript} - (a \href{https://www.gnu.org/software/bash/manual/bash.html}{bash} - script [{\bf \nameref{UpdateScript}}]), work together to finish a PSA installation.\par +% \chapter{Introduction} +\section{Motivation} + +The two main components of a PSA are +\begin{itemize} + \item PTU software. + \item Device controller (DC) firmware. +\end{itemize} + +While the DC firmware is basically the same for each PSA (even for different +customers), the PTU software is highly dependent on customer requirements.\par +Hence, each customer is assigned an own git-repository, which will be loaded +("cloned") on the PSA when configuring the machine for the first time.\par +Two special tools, the {\bf UpdateController} (a \href{https://doc.qt.io/qt-5/}{Qt} +binary [{\bf \nameref{UpdateTool}}]) and the {\bf UpdateScript} +(a \href{https://www.gnu.org/software/bash/manual/bash.html}{bash} +script [{\bf \nameref{UpdateScript}}]), work together to finish a PSA installation.\par - \section{PSA: Initial configuration} - For the initial configuration, a PSA loads a customer-specific git-repository, - which structure is detailed below [{\bf \nameref{repostructure}}].\par - The "git clone" for the repository is done by the UpdateScript [{\bf \nameref{UpdateScript}}]. - It updates the file - \begin{center} - \fbox{ - /opt/app/tools/atbupdate/update\_log.csv - } - \end{center} - which will be interpreted by the UpdateController [{\bf \nameref{UpdateTool}}]. - The structure of {\bf update\_log.csv} is detailed below [{\bf \nameref{updatelogcsv}}].\par - Each line of {\bf update\_log.csv} represents a command for the UpdateController, - which will either download certain files to the DC or execute some - \href{https://openwrt.org/docs/guide-user/additional-software/opkg}{opkg} - commands [{\bf \nameref{opkg}}]. +\section{PSA: Initial configuration} + +For the initial configuration, a PSA loads a customer-specific git-repository, +which structure is detailed below [{\bf \nameref{repostructure}}].\par +The "git clone" for the repository is done by the UpdateScript [{\bf \nameref{UpdateScript}}]. +It updates the file +\begin{center} + \fbox{ + /opt/app/tools/atbupdate/update\_log.csv + } +\end{center} +which will be interpreted by the UpdateController [{\bf \nameref{UpdateTool}}]. +The structure of [{\bf \nameref{updatelogcsv}}] is detailed below.\par +Each line of update\_log.csv represents a command for the UpdateController, +which will either download certain files to the DC or execute some +\href{https://openwrt.org/docs/guide-user/additional-software/opkg}{opkg} +commands [{\bf \nameref{opkg}}]. - \section{PSA: Update} +\section{PSA: Update} + +The update of a PSA is basically managed by \href{https://git-scm.com/}{git}, a +free and open source distributed version control system. Like many other Version +Control Systems, git has a way to fire off custom scripts when certain important +actions occur, so-called \href{https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks}{hooks}. +The hooks used for a PSA update are called {\bf post-checkout} and {\bf post-merge}.\par +The post-checkout hook is called when checking out some branch of the customer-repository +(for instance when cloning the customer repository for the first time). In contrast, +the post-merge hook is called when a \href{https://www.git-scm.com/docs/git-pull}{git pull} +operation has been issued (more precisely, a \href {https://www.git-scm.com/docs/git-fetch}{git-fetch} +followed by a \href{https://www.git-scm.com/docs/git-merge}{git-merge}).\par +Both hooks update the file [{\bf \nameref{updatelogcsv}}], which is interpreted +by the UpdateController in a second step. - \newpage - -\chapter{Update-Tool "up\_dev\_ctrl"} +% \chapter{Update-Tool "up\_dev\_ctrl"} \section{up\_dev\_ctrl} \label{UpdateTool} @@ -79,7 +94,7 @@ \newpage -\chapter{Update-Script "update\_psa"} +% \chapter{Update-Script "update\_psa"} \section{update\_psa} \label{UpdateScript} @@ -98,13 +113,60 @@ \end{itemize} \newpage -\chapter{Annex} +%\chapter{Annex} \section{Structure of a customer git-repository} \label{repostructure} + \subsection{The post-checkout hook} +TODO: checkout\_history + \subsection{The post-merge hook} +They are both located under the {\bf .githooks}-directory - \section{Structure of "update\_log.csv"} - \label{updatelogcsv} +\section{update\_log.csv} +\label{updatelogcsv} + \begin{table}[h!] + \begin{center} + \caption{Initial state of update\_log.csv} + \label{tab:initial_state} + \begin{tabular}{llll} + \textbf{Request} & \textbf{Name} & \textbf{Date} & \textbf{Status}\\ + \hline + \multicolumn{4}{c}{}\\ + DOWNLOAD & /etc/dc/dc2c4.21.bin & 2023-05-01T12:00:00 & N/A\\ + DOWNLOAD & /etc/psa\_config/DC2C\_print01.json & 2023-05-01T12:00:00 & N/A\\ + DOWNLOAD & /etc/psa\_config/DC2C\_print02.json & 2023-05-01T12:00:00 & N/A\\ + DOWNLOAD & /etc/psa\_config/DC2C\_print03.json & 2023-05-01T12:00:00 & N/A\\ + DOWNLOAD & /etc/psa\_config/DC2C\_print04.json & 2023-05-01T12:00:00 & N/A\\ + DOWNLOAD & /etc/psa\_config/DC2C\_print29.json & 2023-05-01T12:00:00 & N/A\\ + DOWNLOAD & /etc/psa\_config/DC2C\_print32.json & 2023-05-01T12:00:00 & N/A\\ + EXECUTE & opkg update & 2023-05-01T12:00:00 & N/A\\ + \end{tabular} + \end{center} + \end{table} + + \begin{table}[h!] + \begin{center} + \caption{State of update\_log.csv after updating} + \label{tab:initial_state} + \begin{tabular}{llll} + \textbf{Request} & \textbf{Name} & \textbf{Date} & \textbf{Status}\\ + \hline + \multicolumn{4}{c}{}\\ + DONE & /etc/dc/dc2c4.21.bin & 2023-05-01T12:00:00 & N/A\\ + DONE & /etc/psa\_config/DC2C\_print01.json & 2023-05-01T12:00:00 & N/A\\ + DONE & /etc/psa\_config/DC2C\_print02.json & 2023-05-01T12:00:00 & N/A\\ + DONE & /etc/psa\_config/DC2C\_print03.json & 2023-05-01T12:00:00 & N/A\\ + DONE & /etc/psa\_config/DC2C\_print04.json & 2023-05-01T12:00:00 & N/A\\ + DONE & /etc/psa\_config/DC2C\_print29.json & 2023-05-01T12:00:00 & N/A\\ + DONE & /etc/psa\_config/DC2C\_print32.json & 2023-05-01T12:00:00 & N/A\\ + DONE & opkg update & 2023-05-01T12:00:00 & N/A\\ + \end{tabular} + \end{center} + \end{table} + + \newpage \section{The package manager "opkg"} \label{opkg} + + \section{Known problems} \end{document}