ATBUpdateTool/doc/update_ptu.tex

\documentclass[12pt]{article}
\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}
\newcommand{\chapter}[1] 
{{\centering          
  \addtocounter{Chapcounter}{1} \Large \underline{\textbf{ \color{blue} Chapter \theChapcounter: ~#1}} }   
  \addcontentsline{toc}{section}{ \color{blue} Chapter:~\theChapcounter~~ #1}    
}
\hypersetup{colorlinks=true}
\hypersetup{linkcolor=black}

\title{Update PTU}
\author{Gerhard Hoffmann}
\date{\today}

\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 
    
\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}
   
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}

        The update-tool is a Qt binary ("up\_dev\_ctrl") and called by the
        system-controller application. It is installed under
        \begin{center}
            \fbox{
                /opt/app/tools/atbupdate/up\_dev\_ctrl
            }
        \end{center}

        and has two responsibilities:
        \begin{itemize}
            \item Call update-script "update\_psa".
            \item Update the device controller firmware.
        \end{itemize}
    \subsection{Calling the update-script "update\_psa"}
        The update-script "update\_psa" is about executing all git-commands
        necessary to clone and pull a customer repository.

    \newpage

% \chapter{Update-Script "update\_psa"}
    \section{update\_psa}
    \label{UpdateScript}

    Inside of such a
        repository, there are at least the following directories:
        \begin{itemize}
           \item {\bf etc} 
           \item {\bf etc/dc}\newline 
                Contains the device controller firmware as binary file.
           \item {\bf etc/psa\_config}\newline
                Contains the printer template files (JSON).
           \item {\bf etc/psa\_tariff}\newline
                Contains the tariff files (JSON).
           \item {\bf etc/psa\_update}\newline
                Contains a single file for opkg-commands.
        \end{itemize}
    \newpage

%\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{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}