GerhardHoffmann/UpdatePTUDevCtrl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

save for the weekend

Browse Source
This commit is contained in:
Gerhard Hoffmann 2023-06-02 14:17:48 +02:00
parent 57b82094c8
commit fa0c31d9e4
1 changed files with 101 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
doc/update_ptu.tex
View File

@ -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}
\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}}].
The two main components of a PSA are
\begin{itemize}
\item PTU software.
\item Device controller (DC) firmware.
\end{itemize}
\section{PSA: Update}
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
\newpage
\section{PSA: Initial configuration}
\chapter{Update-Tool "up\_dev\_ctrl"}
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}
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.
% \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}