From 15c3441aee96cf248fcd65914453e3c655d0b679 Mon Sep 17 00:00:00 2001 From: Matteo Golin Date: Thu, 26 Oct 2023 20:33:59 -0400 Subject: [PATCH] Added an introduction, reformatted .tex files and fixed spelling errors. --- data-logging-format/data_logging_format.tex | 99 ++++----- .../sections/block-formats.tex | 99 ++++----- data-logging-format/sections/introduction.tex | 7 +- .../sections/sd-data-layout.tex | 209 +++++++++--------- 4 files changed, 191 insertions(+), 223 deletions(-) diff --git a/data-logging-format/data_logging_format.tex b/data-logging-format/data_logging_format.tex index a776f83..3254881 100644 --- a/data-logging-format/data_logging_format.tex +++ b/data-logging-format/data_logging_format.tex @@ -5,7 +5,6 @@ \usepackage[hidelinks,bookmarksnumbered]{hyperref} \usepackage[all]{hypcap} \usepackage{fancyhdr} -%\usepackage{sectsty} \usepackage[calcwidth]{titlesec} \usepackage{chngcntr} \usepackage{bytefield} @@ -18,7 +17,7 @@ \usepackage{amsmath} \title{CU InSpace Data Logging Format} -\author{Samuel Dewan} +\author{Samuel Dewan \\ Matteo Golin} % Headers and footers \pagestyle{fancy} @@ -54,76 +53,67 @@ \makebox[0pt][r]{#1\hspace{6pt}}% } \titleformat{\section} - {\sffamily\Large\bfseries} - {\marginsecnumber\thesection} - {0pt} - {} +{\sffamily\Large\bfseries} +{\marginsecnumber\thesection} +{0pt} +{} \titleformat{\subsection} - {\sffamily\large\bfseries} - {\marginsecnumber\thesubsection} - {0pt} - {} +{\sffamily\large\bfseries} +{\marginsecnumber\thesubsection} +{0pt} +{} \titleformat{\subsubsection} - {\sffamily\normalsize\bfseries} - {\marginsecnumber\thesubsubsection} - {0pt} - {} - -% Draft watermark -\usepackage{eso-pic,graphicx} -\AddToShipoutPicture*{% - \AtTextCenter{% - \makebox(0,0)[c]{\resizebox{\textwidth}{!}{% - \rotatebox{45}{\textsf{\textbf{\color{lightgray}DRAFT}}}}} - } -} +{\sffamily\normalsize\bfseries} +{\marginsecnumber\thesubsubsection} +{0pt} +{} % Coloured skipped words command for bytefields \makeatletter \DeclareRobustCommand{\cskippedwords}[2][2ex]{% - \setlength{\units@wide}{\bf@bitwidth * \bits@wide}% - \setlength{\units@high}{1pt * \ratio{\units@wide}{6.0pt}}% - \setlength{\units@tall}{#1 + \units@high}% - \edef\num@wide{\strip@pt\units@wide}% - \edef\num@tall{\strip@pt\units@tall}% - \edef\num@high{\strip@pt\units@high}% - \begin{picture}(\num@wide,\num@tall)% - \begin{tikzpicture}[overlay] - \draw[fill=#2,fill opacity=0.2] - (0,-\bf@bitheight) -- (0,0) -- (0,\units@high) -- (\units@wide,0) -- +(0,-\bf@bitheight) -- cycle; - \draw[fill=#2,fill opacity=0.2] - (0,\units@high+#1+\bf@bitheight) -- ++(\units@wide,0) -- ++(0,-\bf@bitheight-\units@high) -- (0,\units@high+#1) -- cycle; - \end{tikzpicture}% - \end{picture}% - \ifcounting@words - \inc@bytefield@height{\unitlength * \real{\num@tall}}% - \global\counting@wordsfalse - \fi} + \setlength{\units@wide}{\bf@bitwidth * \bits@wide}% + \setlength{\units@high}{1pt * \ratio{\units@wide}{6.0pt}}% + \setlength{\units@tall}{#1 + \units@high}% + \edef\num@wide{\strip@pt\units@wide}% + \edef\num@tall{\strip@pt\units@tall}% + \edef\num@high{\strip@pt\units@high}% + \begin{picture}(\num@wide,\num@tall)% + \begin{tikzpicture}[overlay] + \draw[fill=#2,fill opacity=0.2] + (0,-\bf@bitheight) -- (0,0) -- (0,\units@high) -- (\units@wide,0) -- +(0,-\bf@bitheight) -- cycle; + \draw[fill=#2,fill opacity=0.2] + (0,\units@high+#1+\bf@bitheight) -- ++(\units@wide,0) -- ++(0,-\bf@bitheight-\units@high) -- (0,\units@high+#1) -- cycle; + \end{tikzpicture}% + \end{picture}% + \ifcounting@words + \inc@bytefield@height{\unitlength * \real{\num@tall}}% + \global\counting@wordsfalse + \fi} \makeatother - \begin{document} \frenchspacing \pagenumbering{Alph} \begin{titlepage} -\centering + \centering -\vspace*{\stretch{2}} -{\large \textbf{CU InSpace}} + \vspace*{\stretch{2}} + {\large \textbf{CU InSpace}} -\vspace{\stretch{1}} -{\Huge \sffamily Data Logging Format} + \vspace{\stretch{1}} + {\Huge \sffamily Data Logging Format} -\vspace{\stretch{1}} -{\large \textbf{\today}} + \vspace{\stretch{1}} + {\large \textbf{\today}} -\vspace{\stretch{1}} -Samuel Dewan + \vspace{\stretch{1}} + Samuel Dewan \\ + Matteo Golin -\vspace{\stretch{4}} -\includegraphics[width=0.5\textwidth]{logo.png} -\vspace{\stretch{5}} + \vspace{\stretch{4}} + \includegraphics[width=0.5\textwidth]{logo.png} + \vspace{\stretch{5}} \end{titlepage} @@ -147,5 +137,4 @@ \section{Block Formats} \input{sections/block-formats.tex} \clearpage - \end{document} diff --git a/data-logging-format/sections/block-formats.tex b/data-logging-format/sections/block-formats.tex index 1ca9e0d..e065940 100644 --- a/data-logging-format/sections/block-formats.tex +++ b/data-logging-format/sections/block-formats.tex @@ -1,86 +1,69 @@ \subsection{Logging Metadata Blocks} \label{subsec:logging-metadata-blocks} -Logging metadata blocks are used to store metadata generated by the logging -system and information required in order to correctly parse the logged data. +Logging metadata blocks are used to store metadata generated by the logging system and information required in order to +correctly parse the logged data. -The block types within the Logging Metadata class are described in table -\ref{table:logging-metadata-types}. +The block types within the Logging Metadata class are described in table \ref{table:logging-metadata-types}. \begin{table*}[htb] -\centering -\begin{tabular}{@{}ll@{}} -\toprule -Data Type & Description \\ -\midrule -0x0 & Spacer block \\ -0x1 through 0x3FF & Reserved for future use \\ -\bottomrule -\end{tabular} -\caption{Logging metadata block types} -\label{table:logging-metadata-types} + \centering + \begin{tabular}{@{}ll@{}} + \toprule + Data Type & Description \\ + \midrule + 0x0 & Spacer block \\ + 0x1 through 0x3FF & Reserved for future use \\ + \bottomrule + \end{tabular} + \caption{Logging metadata block types} + \label{table:logging-metadata-types} \end{table*} \subsubsection{Spacer Block} -Spacer blocks are used when writing telemetry data to indicate a region that -does not contain any valid data. When telemetry is being written one SD card -block at a time without the ability to have telemetry data overflow from one -block into another, a spacer block can be used at the end of the SD card block -to take up any excess bytes. - -When parsing, spacer blocks should always be skiped using the length field in -the block header and no attempt should be made to parse a spacer block's -payload. - - +Spacer blocks are used when writing telemetry data to indicate a region that does not contain any valid data. When +telemetry is being written one SD card block at a time without the ability to have telemetry data overflow from one +block into another, a spacer block can be used at the end of the SD card block to take up any excess bytes. +When parsing, spacer blocks should always be skipped using the length field in the block header and no attempt should +be made to parse a spacer block's payload. \subsection{Telemetry Data Blocks} \label{subsec:telemetry-data-blocks} -Data blocks of the Telemetry class follow the formats specified in the CU -InSpace Radio Packet Format document. +Data blocks of the Telemetry class follow the formats specified in the CU InSpace Radio Packet Format document. \subsection{Diagnostic Data Blocks} \label{subsec:diagnostic-data-blocks} -Data blocks with the Diagnostic Data class are used to store information which -is intended to be used for debugging. +Data blocks with the Diagnostic Data class are used to store information which is intended to be used for debugging. -The block types within the Diagnostic Data class are described in table -\ref{table:diagnostic-data-types}. +The block types within the Diagnostic Data class are described in table \ref{table:diagnostic-data-types}. \begin{table*}[htb] -\centering -\begin{tabular}{@{}ll@{}} -\toprule -Data Type & Description \\ -\midrule -0x0 & Log message \\ -0x1 & Outgoing radio packet \\ -0x2 & Incoming radio packet \\ -0x3 through 0x3FF & Reserved for future use \\ -\bottomrule -\end{tabular} -\caption{Diagnostic data block types} -\label{table:diagnostic-data-types} + \centering + \begin{tabular}{@{}ll@{}} + \toprule + Data Type & Description \\ + \midrule + 0x0 & Log message \\ + 0x1 & Outgoing radio packet \\ + 0x2 & Incoming radio packet \\ + 0x3 through 0x3FF & Reserved for future use \\ + \bottomrule + \end{tabular} + \caption{Diagnostic data block types} + \label{table:diagnostic-data-types} \end{table*} \subsubsection{Log Message} -Log messages are string messages intended to provide human readable debugging -output. They are encoded as UTF-8 strings and do not require a terminating NUL -character because the string length can be extrapolated from the block length. +Log messages are string messages intended to provide human readable debugging output. They are encoded as UTF-8 strings +and do not require a terminating NULL character because the string length can be extrapolated from the block length. Every log message is preceded by a 32 bit unsigned mission time value. -Note that like all other data blocks log messages must be a multiple of four -bytes long. If the string to be logged is not a multiple of four bytes it must -be padded with NUL characters at the end to make it fit the required alignment. -The length recorded in the block header must be a multiple of four, and -therefore must include any NUL padding bytes at the end of the string. - -\subsubsection{Outgoing Radio Packet} - -\subsubsection{Incoming Radio Packet} - +Note that like all other data blocks log messages must be a multiple of four bytes long. If the string to be logged is +not a multiple of four bytes it must be padded with NULL characters at the end to make it fit the required alignment. +The length recorded in the block header must be a multiple of four, and therefore must include any NULL padding bytes +at the end of the string. diff --git a/data-logging-format/sections/introduction.tex b/data-logging-format/sections/introduction.tex index 970f764..f1ad320 100644 --- a/data-logging-format/sections/introduction.tex +++ b/data-logging-format/sections/introduction.tex @@ -1 +1,6 @@ -To do. +The following format specification describes how Carleton University InSpace logs telemetry data and diagnostic +information on an SD card from a telemetry device. This format makes use of the CU InSpace radio packet format for +logging telemetry data. This greatly simplifies encoding, and ensures that all outgoing radio messages are recorded in +the case that they are not delivered to the recipient. + +This packet format is made publicly available via the GNUGPLv3 license. diff --git a/data-logging-format/sections/sd-data-layout.tex b/data-logging-format/sections/sd-data-layout.tex index 18bf655..b728f04 100644 --- a/data-logging-format/sections/sd-data-layout.tex +++ b/data-logging-format/sections/sd-data-layout.tex @@ -1,133 +1,124 @@ \subsection{Master Boot Record} -The CU InSpace Avionics system requires SD cards that have been formated with a -Master Boot Record (MBR) in block 0. +The CU InSpace Avionics system requires SD cards that have been formatted with a Master Boot Record (MBR) in block 0. \subsection{Data Partitions} -CU InSpace data is logged into partitions with partion type \textbf{0x89}. A -data logging system will always log into the first valid partition on the disk. -If the first partition becomes full it may continue logging into later +CU InSpace data is logged into partitions with partition type \textbf{0x89}. A data logging system will always log into +the first valid partition on the disk. If the first partition becomes full it may continue logging into later partitions. -CU InSpace logging data partitions are layed out with a single super block -followed by one or more SD Card blocks containing "blocks" of application data. -The application data "blocks" each start with a header which indicates the type -of data in the block and the length of the block. Application data blocks are -stored contiguously and may be stored accross SD Card block boundries. +CU InSpace logging data partitions are laid out with a single super block followed by one or more SD Card blocks +containing "blocks" of application data. The application data "blocks" each start with a header which indicates the +type of data in the block and the length of the block. Application data blocks are stored contiguously and may be +stored across SD Card block boundaries. \subsubsection{Super Block} -Every CU InSpace data partition must start with a Super Block which follows the -format shown in figure \ref{format:superblock}. +Every CU InSpace data partition must start with a Super Block which follows the format shown in figure +\ref{format:superblock}. \begin{figure}[h] -\centering -\begin{bytefield}[leftcurly=.,leftcurlyspace=0pt,bitwidth=0.03\linewidth]{32} - \bitheader{0-31} \\ - \begin{leftwordgroup}{0x00} - \wordbox{2}{Magic Number} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x08} - \bitbox{8}{version} & \bitbox{1}{\rotatebox{90}{\tiny{Cont.}}} & - \bitbox{23}{\color{lightgray}\rule{\width}{\height}} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x0C} - \wordbox{1}{Parition Length} - \end{leftwordgroup} \\ - - \wordbox[lrt]{1}{Reserved} \\ - \cskippedwords{lightgray} \\ - \wordbox[lrb]{1}{} \\ - - \begin{leftwordgroup}{0x60} - \wordbox{1}{Flight 0 First Data Block Offset} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x64} - \wordbox{1}{Flight 0 Last Data Block Offset} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x68} - \wordbox{1}{Flight 0 Timestamp} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x6C} - \wordbox{1}{Flight 1 First Data Block Offset} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x70} - \wordbox{1}{Flight 1 Last Data Block Offset} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x74} - \wordbox{1}{Flight 1 Timestamp} - \end{leftwordgroup} \\ - - \wordbox[lrt]{1}{} \\ - \skippedwords \\ - \wordbox[lrb]{1}{} \\ - - \begin{leftwordgroup}{0x1D4} - \wordbox{1}{Flight 31 First Data Block Offset} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x1D8} - \wordbox{1}{Flight 31 Last Data Block Offset} - \end{leftwordgroup} \\ - \begin{leftwordgroup}{0x1DC} - \wordbox{1}{Flight 31 Timestamp} - \end{leftwordgroup} \\ - - \wordbox[lrt]{1}{Reserved} \\ - \cskippedwords{lightgray} \\ - \wordbox[lrb]{1}{} \\ - - \begin{leftwordgroup}{0x1F8} - \wordbox{2}{Magic Number} - \end{leftwordgroup} \\ -\end{bytefield} -\caption{Super block format} -\label{format:superblock} + \centering + \begin{bytefield}[leftcurly=.,leftcurlyspace=0pt,bitwidth=0.03\linewidth]{32} + \bitheader{0-31} \\ + \begin{leftwordgroup}{0x00} + \wordbox{2}{Magic Number} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x08} + \bitbox{8}{version} & \bitbox{1}{\rotatebox{90}{\tiny{Cont.}}} & + \bitbox{23}{\color{lightgray}\rule{\width}{\height}} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x0C} + \wordbox{1}{Partition Length} + \end{leftwordgroup} \\ + + \wordbox[lrt]{1}{Reserved} \\ + \cskippedwords{lightgray} \\ + \wordbox[lrb]{1}{} \\ + + \begin{leftwordgroup}{0x60} + \wordbox{1}{Flight 0 First Data Block Offset} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x64} + \wordbox{1}{Flight 0 Last Data Block Offset} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x68} + \wordbox{1}{Flight 0 Timestamp} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x6C} + \wordbox{1}{Flight 1 First Data Block Offset} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x70} + \wordbox{1}{Flight 1 Last Data Block Offset} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x74} + \wordbox{1}{Flight 1 Timestamp} + \end{leftwordgroup} \\ + + \wordbox[lrt]{1}{} \\ + \skippedwords \\ + \wordbox[lrb]{1}{} \\ + + \begin{leftwordgroup}{0x1D4} + \wordbox{1}{Flight 31 First Data Block Offset} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x1D8} + \wordbox{1}{Flight 31 Last Data Block Offset} + \end{leftwordgroup} \\ + \begin{leftwordgroup}{0x1DC} + \wordbox{1}{Flight 31 Timestamp} + \end{leftwordgroup} \\ + + \wordbox[lrt]{1}{Reserved} \\ + \cskippedwords{lightgray} \\ + \wordbox[lrb]{1}{} \\ + + \begin{leftwordgroup}{0x1F8} + \wordbox{2}{Magic Number} + \end{leftwordgroup} \\ + \end{bytefield} + \caption{Super block format} + \label{format:superblock} \end{figure} \subsection{Data Blocks} -Every data block starts with a four byte block header. This header indicates the -type of information contained in the block. The block header format is described -in figure \ref{format:block-header}. +Every data block starts with a four byte block header. This header indicates the type of information contained in the +block. The block header format is described in figure \ref{format:block-header}. \begin{figure}[h] -\centering -\begin{bytefield}[bitwidth=0.03\linewidth]{32} - \bitheader{0-31} \\ - \bitbox{6}{Class} & - \bitbox{10}{Type} & - \bitbox{16}{Length} -\end{bytefield} -\caption{Block header format} -\label{format:block-header} + \centering + \begin{bytefield}[bitwidth=0.03\linewidth]{32} + \bitheader{0-31} \\ + \bitbox{6}{Class} & + \bitbox{10}{Type} & + \bitbox{16}{Length} + \end{bytefield} + \caption{Block header format} + \label{format:block-header} \end{figure} -The \emph{Class} and \emph{Type} fields are used to specify how the data block -should be interpreted. The \emph{Length} field specifies the length in bytes of -the data block including the block header. This length field can be used to find -the start of the next data block when parsing and can also be used in parsing -data blocks for which the format does not specify a fixed length. The -\emph{Length} value must always be a multiple of four bytes. A length of zero is -invalid. +The \emph{Class} and \emph{Type} fields are used to specify how the data block should be interpreted. The \emph{Length} +field specifies the length in bytes of the data block including the block header. This length field can be used to find +the start of the next data block when parsing and can also be used in parsing data blocks for which the format does not +specify a fixed length. The \emph{Length} value must always be a multiple of four bytes. A length of zero is invalid. -Table \ref{table:block-classes} shows the possible values for the \emph{Class} -field in the data block header. Section \ref{sec:block-formats} describes the -data formats for blocks of each of the classes. +Table \ref{table:block-classes} shows the possible values for the \emph{Class} field in the data block header. Section +\ref{sec:block-formats} describes the data formats for blocks of each of the classes. \begin{table*}[htb] -\centering -\begin{tabular}{@{}ll@{}} -\toprule -Data Block Class & Description \\ -\midrule -0x0 & Logging Metadata (see section \ref{subsec:logging-metadata-blocks}) \\ -0x1 & Telemetry Data (see section \ref{subsec:telemetry-data-blocks})\\ -0x2 & Diagnostic Data (see section \ref{subsec:diagnostic-data-blocks}) \\ -0x3 through 0x3F & Reserved for future use \\ -\bottomrule -\end{tabular} -\caption{Data Block Classes} -\label{table:block-classes} + \centering + \begin{tabular}{@{}ll@{}} + \toprule + Data Block Class & Description \\ + \midrule + 0x0 & Logging Metadata (see section \ref{subsec:logging-metadata-blocks}) \\ + 0x1 & Telemetry Data (see section \ref{subsec:telemetry-data-blocks}) \\ + 0x2 & Diagnostic Data (see section \ref{subsec:diagnostic-data-blocks}) \\ + 0x3 through 0x3F & Reserved for future use \\ + \bottomrule + \end{tabular} + \caption{Data Block Classes} + \label{table:block-classes} \end{table*} -