Minor: add doxygen comments

.gitignore

@@ -1,3 +1,4 @@
 tags
 *.tags
 *.user
+documentation/

UpdatePTUDevCtrl/main.cpp

@@ -50,25 +50,32 @@
 #endif
 
 /**
- * @mainpage ATBUpdateTool Documentation
- * @section intro_sec Introduction
- * TODO.
- * @section atbupdate_tool ATBUpdateTool
- * TODO.
- * @section atbupdate_check ATBUpdateCheck
- * TODO
- * @section atbupdate_git ATBUpdateGit
- * TODO
- * @section atbupdate_sync ATBUpdateSync
- * TODO
- * @section atbupdate_opkg ATBUpdateOpkg
- * TODO
- * @section atbupdate_dc ATBUpdateDC
- * TODO
- * @section atbupdate_json_files ATBUpdateJsonFiles
- * TODO
- * @section atbupdate_show ATBUpdateShow
- * TODO
+ * @mainpage ATB-Update-Tool Documentation
+ * \section intro_sec Introduction
+ *  The ATB update tool consistes of several binaries, which are executed in
+ *  order:
+ *  * \ref ATBUpdateTool
+ *  * \ref ATBUpdateCheck
+ *  * \ref ATBUpdateGit
+ *  * \ref ATBUpdateSync
+ *  * \ref ATBUpdateOpkg
+ *  * \ref ATBUpdateDC
+ *  * \ref ATBUpdateJsonFiles
+ *  * \ref ATBUpdateShow
+ *
+ *  The binaries are started synchonously as child processes of \ref ATBUpdateTool:
+ *  each binary will finish before the next one is started.
+ *  The output for the child process is captured in \ref ATBUpdateTool, and
+ *  optionally shown in the GUI presemted to the user.
+ *
+ * - \page ATBUpdateTool
+ * - \page ATBUpdateCheck
+ * - \page ATBUpdateGit
+ * - \page ATBUpdateSync
+ * - \page ATBUpdateOpkg
+ * - \page ATBUpdateDC
+ * - \page ATBUpdateJsonFiles
+ * - \page ATBUpdateShow
  */
 
 // argv[1]: file to send to dc

UpdatePTUDevCtrl/work_process_list.cpp

@@ -4,12 +4,12 @@
 #include <limits>
 #include <QDebug>
 
-unsigned WorkList::nextExecIndex() const {
-    if (m_workList.size() > 0 && m_workListIndex < (m_workList.size() - 1)) {
-        return m_workListIndex + 1;
-    }
-    return std::numeric_limits<unsigned>::max();
-}
+//unsigned WorkList::nextExecIndex() const {
+//    if (m_workList.size() > 0 && m_workListIndex < (m_workList.size() - 1)) {
+//        return m_workListIndex + 1;
+//    }
+//    return std::numeric_limits<unsigned>::max();
+//}
 
 bool WorkList::nextExec() const {
     return m_workListIndex < m_workList.size();
@@ -17,12 +17,17 @@ bool WorkList::nextExec() const {
 
 bool WorkList::exec(bool last) {
     if (last == false) {
+        // if not the last entry in the worklist
         if (nextExec()) {
+            // and there is a next entry (a binary) to execute, start the
+            // binary if the specified working directory.
             m_workList[m_workListIndex]->start("/opt/app/tools/atbupdate");
+            // update to point to next entry
             m_workListIndex += 1;
             return true;
         }
     } else {
+        // start the last entry in the worklist
         m_workList.back()->start("/opt/app/tools/atbupdate");
         m_workListIndex = std::numeric_limits<unsigned>::max();
         return true;

UpdatePTUDevCtrl/work_process_list.h

@@ -5,18 +5,42 @@
 #include <memory>
 
 class UpdateCommand;
+
+
+/**
+ * @brief This class is responsible for calling the several binaries
+ * \ref ATBUpdateTool consists of.
+ *
+ * This class maintains a worklist, which conists of entries of type UpdateCommand.
+ *
+ * @see UpdateCommand
+ */
 class WorkList {
-public:
+    /**
+     * @brief Actual worklist of items to be eecuted.
+     */
     std::vector<std::unique_ptr<UpdateCommand>> m_workList;
+public:
     unsigned m_workListIndex{0};
 
     WorkList() = default;
 
+    /**
+     * \brief Put new work item into worklist.
+     *
+     * \tparam arg Work item to be added to worklist.
+     */
     template<typename T>
     void push_back(T&& arg) {
         m_workList.push_back(std::forward<T>(arg));
     }
 
+    /**
+     * \brief Check if worklist is empty.
+     *
+     * \retval true if worklist is empty.
+     * \retval false otherwise.
+     */
     bool empty() const { return m_workList.empty(); }
 
     // move constructor: pass in classes derived from UpdateCommand
@@ -28,10 +52,30 @@ public:
     //  , m_workListIndex(0) {
     //}
 
-    unsigned nextExecIndex() const;
+    ///**
+    // * \brief Put new work item into worklist.
+    // *
+    // */
+    //unsigned nextExecIndex() const;
+
+    /**
+     * \brief Put new work item into worklist.
+     *
+     */
     bool nextExec() const;
+
+    /**
+     * \brief Put new work item into worklist.
+     *
+     * \param last
+     */
     bool exec(bool last=false);
 
+    /**
+     * \brief Get current size of worklist.
+     *
+     * \retval Current size of worklist.
+     */
     unsigned size() { return m_workList.size(); }
 };
 

misc/on_update_failure.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+
+# set -x
+
+#
+#############################################################################
+# Check if the ATBUpdateTool(.service) did not send U0001 (sucess),
+# U0002 (activated) or U0003 (error) to ISMAS, including the case that the
+# tool did not crash or was not killed under other circumstances.
+#
+# This script will be called in the associated atbupdatetool.service (see
+# /lib/systemd/system/atbupdatetool.service).
+#
+###############################################################################
+
+readonly OUT_FILE=/tmp/out.txt
+readonly SCRIPT_NAME=$(basename $0)
+
+if [ -z "$START_DATE" ]
+then
+    START_DATE=$(date +"%Y-%m-%d00:00:00")
+fi
+
+if [ -z "$STOP_DATE" ]
+then
+    STOP_DATE=$(date +"%Y-%m-%d%H:%M:%S")
+fi
+
+echo "EXIT_CODE=$EXIT_CODE"
+echo "SERVICE_RESULT=$SERVICE_RESULT"
+echo "EXIT_STATUS=$EXIT_STATUS"
+echo "START_DATE=$START_DATE"
+echo "STOP_DATE=$STOP_DATE"
+
+
+last_cmd_event () {
+    # output json; look for start of CMD_EVENT; look for }}; extract everything between; finally re-add }}.
+    # could also look for ">>>", but this might change in the future.
+    local json=$(\
+	    journalctl -u atbupdatetool --since="$START_DATE" --until="$STOP_DATE" --output=json-pretty |\
+	    grep "#M=APISM#C=CMD_EVENT#J="                                                              |\
+	    awk '{split($0, a, "#M=APISM#C=CMD_EVENT#J="); print a[2]}'                                 |\
+	    awk '{split($0, a, /\}[\s]*\}/); print a[1]}'                                               |\
+	    tr -d '\\'                                                                                  |\
+	    tail -1)
+    json+="}}"
+    echo "$json"
+}
+
+last_percent_value () {
+    echo $(cat $OUT_FILE | sed -n "s/\(^.*\)\(\"PERCENT\"\\s*:\)\(\\s*[0-9]\+\)\(.*$\)/\3/p" | xargs | awk '{print $NF}')
+}
+
+last_step () {
+    echo $(cat $OUT_FILE | sed -n "s/\(^.*\)\(\"PERCENT\"\\s*:\)\(\\s*[0-9]\+\)\(.*$\)/\1\2\3\4/p" | tail -1 | awk '{split($0, a, ","); print a[8]}' | awk '{split($0, b, " : "); print b[2]}' | tr -d '"\\')
+}
+
+last_step_result () {
+    echo $(cat $OUT_FILE | sed -n "s/\(^.*\)\(\"PERCENT\"\\s*:\)\(\\s*[0-9]\+\)\(.*$\)/\1\2\3\4/p" | tail -1 | awk '{split($0, a, ","); print a[9]}' | awk '{split($0, b, " : "); print b[2]}' | tr -d '"\\')
+}
+
+pid_atbupdatetool () {
+    echo $(cat $OUT_FILE | sed -n "s/\(^.*\)\(ATBUpdateTool\[\)\(\\s*[0-9]\+\)\(\].*$\)/\3/p" | uniq)
+}
+
+last_event () {
+    echo $(cat $OUT_FILE | sed -n "s/\(^.*\)\(\"PERCENT\"\\s*:\)\(\\s*[0-9]\+\)\(.*$\)/\1\2\3\4/p" | tail -1 | awk '{split($0, a, ","); print a[4]}' | awk '{split($0, b, ":"); print b[2]}' | tr -d ' ' | tr -d '"\\') 
+}
+
+sendU0003 () {
+    LAST_CMD_EVENT=$(last_cmd_event)
+    echo "LAST=$LAST_CMD_EVENT"
+    
+    local json_detected=0
+    local temp
+    local x
+
+    if [[ ! -z "$LAST_CMD_EVENT" ]]
+    then
+       temp=$(mktemp -p /tmp)
+       echo "$LAST_CMD_EVENT" > "$temp"
+       x=$(jq .EVENT $temp)
+       if [ $? -eq 0 ]; then
+           json_detected=1
+       fi
+    fi
+
+    if [ $json_detected -eq 1 ]
+    then
+        # local pid=$(jq .EVENT_ID $temp)
+
+	# if json has been detected, use "jq".
+
+        x=$(jq .PARAMETER.PERCENT $temp | tr -d '"')
+        [[ -z "$x" ]] && PERCENT=0 || PERCENT=$x
+
+        x=$(jq .PARAMETER.STEP $temp | tr -d '"')
+        [[ -z "$x" ]] && STEP="unknown" || STEP="$x"
+       
+        x=$(jq .PARAMETER.STEP_RESULT $temp | tr -d '"')
+        [[ -z "$x" ]] && STEP_RESULT="unknown" || STEP_RESULT="$x"
+    
+        x=$(pid_atbupdatetool)
+        [[ -z "$x" ]] && PID=99999 || PID=$x
+    
+        x=$(last_event)
+        [[ -z "$x" ]] && EVENT="unknown" || EVENT="$x"
+    
+    else 
+        # cannot parse valid json. try original journal text file.
+
+        x=$(last_percent_value)
+        [[ -z "$x" ]] && PERCENT=0 || PERCENT=$x
+
+        x=$(last_step)
+        [[ -z "$x" ]] && STEP="unknown" || STEP="$x"
+    
+        x=$(last_step_result)
+        [[ -z "$x" ]] && STEP_RESULT="unknown" || STEP_RESULT="$x"
+    
+        x=$(pid_atbupdatetool)
+        [[ -z "$x" ]] && PID=99999 || PID=$x
+
+        x=$(last_event)
+        [[ -z "$x" ]] && EVENT="unknown" || EVENT="$x"
+    fi
+
+    echo "PERCENT=$PERCENT"
+    echo "STEP=$STEP"
+    echo "STEP_RESULT=$STEP_RESULT"
+    echo "PID=$PID"
+    echo "EVENT=$EVENT"
+
+    # build json to be sent to ISMAS with "U0003"
+
+    CURRENT_DATE=$(date +"%Y-%m-%d %H:%M:%S.000%z")
+    U0003Msg="{\
+        \"REASON\":\"SW_UP\",\
+        \"TIMESTAMP\":\"$CURRENT_DATE\",\
+        \"EVENT_ID\":\"$PID\",\
+        \"EVENT\":\"U0003\",\
+        \"EVENTSTATE\":1,\
+        \"PARAMETER\": {\
+            \"PERCENT\" : $PERCENT,\
+            \"RESULTCODE\" : 99,\
+                    \"STEP\" : \"$1 -> monitored last step: $STEP\",\
+                    \"STEP_RESULT\" : \"$1 -> monitored last step result: $STEP_RESULT\",\
+            \"VERSION\" : \"\"\
+        }\
+    }"
+
+    echo -e "U0003Msg=$U0003Msg"
+
+    (echo "#M=APISM#C=CMD_EVENT#J=$U0003Msg"; sleep 5) | nc localhost 7777
+}
+
+# save journal for the last run of atbupdatetool in $OUT_FILE
+echo $(journalctl -u atbupdatetool --since="$START_DATE" --until=$STOP_DATE) > $OUT_FILE
+
+if [[ "$EXIT_CODE" = "exited" && "$SERVICE_RESULT" = "success" && "$EXIT_STATUS" = "0" ]]
+then
+    # almost normal run; at least there was no crash.	
+    if cat $OUT_FILE | grep -o "U0003" | wc -l; then
+        echo "$SCRIPT_NAME: Failure code U0003 already sent to ISMAS"
+        exit 0
+    fi
+
+    if cat $OUT_FILE | grep -o "U0002" | wc -l; then
+        echo "$SCRIPT_NAME: Success code U0002 already sent to ISMAS"
+        exit 0
+    else
+        sendU0003 "$SCRIPT_NAME: Success code U0002 not sent to ISMAS"
+    fi
+
+    if cat $OUT_FILE | grep -o "U0001" | wc -l; then
+        echo "$SCRIPT_NAME: Success code U0001 already sent to ISMAS"
+        exit 0
+    else
+        sendU0003 "$SCRIPT_NAME: Success code U0001 not sent to ISMAS"
+    fi
+else
+    # something unexpected has happened.
+    sendU0003 "$SCRIPT_NAME: EXIT_CODE=$EXIT_CODE;SERVICE_RESULT=$SERVICE_RESULT;EXIT_STATUS=$EXIT_STATUS"
+fi