Cheryl He / telemetry-master

setup

telemetry-master/docs/quickstart.tex@0:fc22cf8cc478, 2015-05-05 (annotated)

Committer:
cheryl_he
Date:
Tue May 05 00:43:17 2015 +0000
Revision:
0:fc22cf8cc478
telemetry setup

Who changed what in which revision?

UserRevisionLine numberNew contents of line
cheryl_he 0:fc22cf8cc478 1 \documentclass[11pt]{article}
cheryl_he 0:fc22cf8cc478 2 \usepackage{graphicx}
cheryl_he 0:fc22cf8cc478 3 \usepackage{hyperref}
cheryl_he 0:fc22cf8cc478 4 \usepackage{xcolor}
cheryl_he 0:fc22cf8cc478 5 \usepackage{listings}
cheryl_he 0:fc22cf8cc478 6
cheryl_he 0:fc22cf8cc478 7 \newcommand{\todo}[1]{\textcolor{red}{\textbf{TODO:} #1}}
cheryl_he 0:fc22cf8cc478 8
cheryl_he 0:fc22cf8cc478 9 % lifted from http://timmurphy.org/2014/01/27/displaying-code-in-latex-documents/
cheryl_he 0:fc22cf8cc478 10 \lstset{
cheryl_he 0:fc22cf8cc478 11 basicstyle=\ttfamily\footnotesize,
cheryl_he 0:fc22cf8cc478 12 breaklines=true,
cheryl_he 0:fc22cf8cc478 13 frame=tb, % draw a frame at the top and bottom of the code block
cheryl_he 0:fc22cf8cc478 14 tabsize=2, % tab space width
cheryl_he 0:fc22cf8cc478 15 showstringspaces=false, % don't mark spaces in strings
cheryl_he 0:fc22cf8cc478 16 numbers=left, % display line numbers on the left
cheryl_he 0:fc22cf8cc478 17 commentstyle=\color{green}, % comment color
cheryl_he 0:fc22cf8cc478 18 keywordstyle=\color{blue}, % keyword color
cheryl_he 0:fc22cf8cc478 19 stringstyle=\color{red} % string color
cheryl_he 0:fc22cf8cc478 20 }
cheryl_he 0:fc22cf8cc478 21
cheryl_he 0:fc22cf8cc478 22 \title{\textbf{Telemetry Quick Start \& Reference}}
cheryl_he 0:fc22cf8cc478 23 \author{Ducky}
cheryl_he 0:fc22cf8cc478 24 \date{\today}
cheryl_he 0:fc22cf8cc478 25 \begin{document}
cheryl_he 0:fc22cf8cc478 26
cheryl_he 0:fc22cf8cc478 27 \maketitle
cheryl_he 0:fc22cf8cc478 28
cheryl_he 0:fc22cf8cc478 29 \section{Introduction}
cheryl_he 0:fc22cf8cc478 30 The telemetry library is designed to provide a simple and efficient way to get data off an embedded platform and both visualized and logged on a PC. The intended use case is streaming data from an embedded system to a PC through an UART interface (possibly on top of either a USB or Bluetooth transport layer). Since data definitions are transmitted, user-side code changes can be limited to the data source side, eliminating the need to keep both the source-side and sink-side code in sync.
cheryl_he 0:fc22cf8cc478 31
cheryl_he 0:fc22cf8cc478 32 The server-side (data source) code is written in C++ and designed with embedded constraints in mind (mainly, no dynamic memory allocation is done). Templated classes are used to support most native data types and a hardware abstraction layer allows multiple platforms (including Arduino and mBed) to be supported.
cheryl_he 0:fc22cf8cc478 33
cheryl_he 0:fc22cf8cc478 34 The client-side (data sink) code is written in Python. A basic telemetry protocol parser is provided that separates and interprets telemetry packets and other data from the received stream. A matplotlib-based GUI is also provided on top of the parser that visualizes numeric data as a line plot and array-numeric data as a waterfall / spectrogram style plot.
cheryl_he 0:fc22cf8cc478 35
cheryl_he 0:fc22cf8cc478 36 A protocol spec is also given allowing other implementations of either the server and client. It short, it defines a binary wire format along with packet structures for data and headers.
cheryl_he 0:fc22cf8cc478 37
cheryl_he 0:fc22cf8cc478 38 \section{Prerequisites}
cheryl_he 0:fc22cf8cc478 39 The following software is necessary for a basic telemetry install:
cheryl_he 0:fc22cf8cc478 40 \begin{itemize}
cheryl_he 0:fc22cf8cc478 41 \item \href{https://www.python.org/downloads/}{Python} (this document was written for 3.4, but may work on 2.7)
cheryl_he 0:fc22cf8cc478 42 \end{itemize}
cheryl_he 0:fc22cf8cc478 43
cheryl_he 0:fc22cf8cc478 44 The following software is necessary for the telemetry plotter GUI:
cheryl_he 0:fc22cf8cc478 45 \begin{itemize}
cheryl_he 0:fc22cf8cc478 46 \item \href{http://sourceforge.net/projects/numpy/files/NumPy/}{NumPy (1.9.2 or later)}
cheryl_he 0:fc22cf8cc478 47 \begin{itemize}
cheryl_he 0:fc22cf8cc478 48 \item \href{http://sourceforge.net/projects/numpy/files/NumPy/1.9.2/numpy-1.9.2-win32-superpack-python3.4.exe/download}{executable for Windows, Python 3.4 32-bit}
cheryl_he 0:fc22cf8cc478 49 \end{itemize}
cheryl_he 0:fc22cf8cc478 50 \item \href{http://matplotlib.org/downloads.html}{matplotlib (1.4.3 or later)}
cheryl_he 0:fc22cf8cc478 51 \begin{itemize}
cheryl_he 0:fc22cf8cc478 52 \item \href{http://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.4.3/windows/matplotlib-1.4.3.win32-py3.4.exe/download}{executable for Windows, Python 3.4 32-bit}
cheryl_he 0:fc22cf8cc478 53 \end{itemize}
cheryl_he 0:fc22cf8cc478 54 \end{itemize}
cheryl_he 0:fc22cf8cc478 55
cheryl_he 0:fc22cf8cc478 56 \subsection{Windows Install}
cheryl_he 0:fc22cf8cc478 57 \begin{enumerate}
cheryl_he 0:fc22cf8cc478 58 \item Install the prerequisite software above.
cheryl_he 0:fc22cf8cc478 59 \item Install the required Python packages via \texttt{pip}:
cheryl_he 0:fc22cf8cc478 60 \begin{verbatim}
cheryl_he 0:fc22cf8cc478 61 cd C:\Python34\Scripts
cheryl_he 0:fc22cf8cc478 62 pip install pyserial
cheryl_he 0:fc22cf8cc478 63 \end{verbatim}
cheryl_he 0:fc22cf8cc478 64 \item If using the plotter GUI, also install these Python dependencies for matplotlib via \texttt{pip}:
cheryl_he 0:fc22cf8cc478 65 \begin{verbatim}
cheryl_he 0:fc22cf8cc478 66 cd C:\Python34\Scripts
cheryl_he 0:fc22cf8cc478 67 pip install six python-dateutil pyparsing
cheryl_he 0:fc22cf8cc478 68 \end{verbatim}
cheryl_he 0:fc22cf8cc478 69 \end{enumerate}
cheryl_he 0:fc22cf8cc478 70
cheryl_he 0:fc22cf8cc478 71 \subsection{Linux Install}
cheryl_he 0:fc22cf8cc478 72 \todo{to be written}
cheryl_he 0:fc22cf8cc478 73
cheryl_he 0:fc22cf8cc478 74 \section{Known Issues}
cheryl_he 0:fc22cf8cc478 75 \subsection{Telemetry framework}
cheryl_he 0:fc22cf8cc478 76 \begin{itemize}
cheryl_he 0:fc22cf8cc478 77 \item No CRC support yet.
cheryl_he 0:fc22cf8cc478 78 \item Packets do not time out on the receiver side yet.
cheryl_he 0:fc22cf8cc478 79 \item Receivers can't request that the header packet be re-sent.
cheryl_he 0:fc22cf8cc478 80 \end{itemize}
cheryl_he 0:fc22cf8cc478 81
cheryl_he 0:fc22cf8cc478 82 \subsection{Plotter GUI}
cheryl_he 0:fc22cf8cc478 83 \begin{itemize}
cheryl_he 0:fc22cf8cc478 84 \item Waterfall / spectrogram-style plotting is highly inefficient (but serviceable).
cheryl_he 0:fc22cf8cc478 85 \end{itemize}
cheryl_he 0:fc22cf8cc478 86
cheryl_he 0:fc22cf8cc478 87 \subsection{mBed HAL}
cheryl_he 0:fc22cf8cc478 88 \begin{itemize}
cheryl_he 0:fc22cf8cc478 89 \item MODSERIAL and Serial putc is highly inefficient for multi-byte data, having high overhead (at 1 Mbaud, the overhead is about 3x the time to transmit the byte). Using MODDMA may increase efficiency.
cheryl_he 0:fc22cf8cc478 90 \end{itemize}
cheryl_he 0:fc22cf8cc478 91
cheryl_he 0:fc22cf8cc478 92 \subsection{Arduino HAL}
cheryl_he 0:fc22cf8cc478 93 \begin{itemize}
cheryl_he 0:fc22cf8cc478 94 \item None yet
cheryl_he 0:fc22cf8cc478 95 \end{itemize}
cheryl_he 0:fc22cf8cc478 96
cheryl_he 0:fc22cf8cc478 97 \section{Transmit-side Quick Start Guide}
cheryl_he 0:fc22cf8cc478 98 All the transmit-side code is contained in (repository base)\texttt{/server-cpp}.
cheryl_he 0:fc22cf8cc478 99
cheryl_he 0:fc22cf8cc478 100 \subsection{Build system setup}
cheryl_he 0:fc22cf8cc478 101 \begin{itemize}
cheryl_he 0:fc22cf8cc478 102 \item Add all the \texttt{.h} header files to your compiler's include path.
cheryl_he 0:fc22cf8cc478 103 \item Add all the \texttt{.cpp} source files to your build path - these should end up compiled into your code.
cheryl_he 0:fc22cf8cc478 104 \end{itemize}
cheryl_he 0:fc22cf8cc478 105
cheryl_he 0:fc22cf8cc478 106 \subsection{Code setup}
cheryl_he 0:fc22cf8cc478 107 \begin{itemize}
cheryl_he 0:fc22cf8cc478 108 \item Include the telemetry header in your code:
cheryl_he 0:fc22cf8cc478 109 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 110 #include "telemetry.h"
cheryl_he 0:fc22cf8cc478 111 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 112 \item Include the HAL for your platform: either \texttt{telemetry-arduino.h} or \texttt{telemetry-mbed.h}
cheryl_he 0:fc22cf8cc478 113 \end{itemize}
cheryl_he 0:fc22cf8cc478 114
cheryl_he 0:fc22cf8cc478 115 \subsection{Usage}
cheryl_he 0:fc22cf8cc478 116 \begin{itemize}
cheryl_he 0:fc22cf8cc478 117 \item Instantiate both a telemetry HAL (again, for your platform) and a \texttt{Telemetry} object: \\
cheryl_he 0:fc22cf8cc478 118 Arduino example using \texttt{Serial1} as the UART pins:
cheryl_he 0:fc22cf8cc478 119 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 120 telemetry::ArduinoHalInterface telemetry_hal(Serial1);
cheryl_he 0:fc22cf8cc478 121 telemetry::Telemetry telemetry_obj(telemetry_hal);
cheryl_he 0:fc22cf8cc478 122 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 123 mBed example using \texttt{PTA2} as UART transmit and \texttt{PTA1} as UART receive:
cheryl_he 0:fc22cf8cc478 124 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 125 MODSERIAL telemetry_serial(PTA2, PTA1);
cheryl_he 0:fc22cf8cc478 126 telemetry::MbedHal telemetry_hal(telemetry_serial);
cheryl_he 0:fc22cf8cc478 127 telemetry::Telemetry telemetry_obj(telemetry_hal);
cheryl_he 0:fc22cf8cc478 128 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 129 \item Instantiate telemetry data objects:
cheryl_he 0:fc22cf8cc478 130 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 131 telemetry::Numeric<uint32_t> tele_time_ms(telemetry_obj, "time", "Time", "ms", 0);
cheryl_he 0:fc22cf8cc478 132 telemetry::NumericArray<uint16_t, 128> tele_linescan(telemetry_obj, "linescan", "Linescan", "ADC", 0);
cheryl_he 0:fc22cf8cc478 133 telemetry::Numeric<float> tele_motor_pwm(telemetry_obj, "motor", "Motor PWM", "%DC", 0);
cheryl_he 0:fc22cf8cc478 134 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 135 The constructor signatures are:
cheryl_he 0:fc22cf8cc478 136 \begin{itemize}
cheryl_he 0:fc22cf8cc478 137 \item \texttt{template <typename T>\\ Numeric(Telemetry\& telemetry\_container, const char* internal\_name, const char* display\_name, const char* units, T init\_value)} \\
cheryl_he 0:fc22cf8cc478 138 \texttt{Numeric} describes numeric data of type \texttt{T}. Only 8-, 16- and 32-bit unsigned integers and single-precision floats are currently supported (but why would you use double-precision on a dinky embedded processor?!).
cheryl_he 0:fc22cf8cc478 139 \begin{itemize}
cheryl_he 0:fc22cf8cc478 140 \item \texttt{telemetry\_container}: a reference to a \texttt{Telemetry} object to associate this data with.
cheryl_he 0:fc22cf8cc478 141 \item \texttt{internal\_name}: a string giving this object an internal name to be referenced in code.
cheryl_he 0:fc22cf8cc478 142 \item \texttt{display\_name}: a string giving this object a human-friendly name.
cheryl_he 0:fc22cf8cc478 143 \item \texttt{units}: units this data record is in (not currently used, but may be useful for automation later).
cheryl_he 0:fc22cf8cc478 144 \item \texttt{init\_value}: initial value.
cheryl_he 0:fc22cf8cc478 145 \end{itemize}
cheryl_he 0:fc22cf8cc478 146 \item \texttt{template <typename T, uint32\_t array\_count>\\ NumericArray(Telemetry\& telemetry\_container, const char* internal\_name, const char* display\_name, const char* units, T elem\_init\_value)} \\
cheryl_he 0:fc22cf8cc478 147 \texttt{NumericArray} describes an array of numeric objects of type \texttt{T}. Same constraints apply as from Numeric. The array size \texttt{array\_count} is a template parameter (constant of sorts) to avoid dynamic memory allocations.
cheryl_he 0:fc22cf8cc478 148 \begin{itemize}
cheryl_he 0:fc22cf8cc478 149 \item \texttt{telemetry\_container}: a reference to a \texttt{Telemetry} object to associate this data with.
cheryl_he 0:fc22cf8cc478 150 \item \texttt{internal\_name}: a string giving this object an internal name to be referenced in code.
cheryl_he 0:fc22cf8cc478 151 \item \texttt{display\_name}: a string giving this object a human-friendly name.
cheryl_he 0:fc22cf8cc478 152 \item \texttt{units}: units this data record is in (not currently used, but may be useful for automation later).
cheryl_he 0:fc22cf8cc478 153 \item \texttt{elem\_init\_value}: initial value of array elements.
cheryl_he 0:fc22cf8cc478 154 \end{itemize}
cheryl_he 0:fc22cf8cc478 155 \end{itemize}
cheryl_he 0:fc22cf8cc478 156 \item You can optionally specify additional parameters on the data objects. The only one is the numerical value limits, which can be used to set manual plot bounds on a data visualizer.
cheryl_he 0:fc22cf8cc478 157 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 158 telemetry::Numeric<float> tele_motor_pwm(telemetry_obj, "motor", "Motor PWM", "%DC", 0);
cheryl_he 0:fc22cf8cc478 159 tele_motor_pwm.set_limits(0, 1);
cheryl_he 0:fc22cf8cc478 160 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 161 Note that this (currently) does not affect the embedded code at all - the values will not be clipped nor will warnings / errors be thrown if an out-of-bounds value if set.
cheryl_he 0:fc22cf8cc478 162 \item Transmit the data definitions once at the beginning of your code, after you have finished defining all the data.
cheryl_he 0:fc22cf8cc478 163 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 164 telemetry_obj.transmit_header();
cheryl_he 0:fc22cf8cc478 165 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 166 \item Load data to be transmitted into the telemetry objects. \\
cheryl_he 0:fc22cf8cc478 167 These objects contain the code necessary to transmit and receive telemetry data, but otherwise behave similarly to their template types. For example, you can use the \texttt{tele\_linescan} object as an array:
cheryl_he 0:fc22cf8cc478 168 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 169 telemetry::NumericArray<uint16_t, 128> tele_linescan(telemetry_obj, "linescan", "Linescan", "ADC", 0);
cheryl_he 0:fc22cf8cc478 170 ...
cheryl_he 0:fc22cf8cc478 171 uint16_t* data = cam1.read();
cheryl_he 0:fc22cf8cc478 172 for (uint16_t i=0; i<CAMERA_PIXEL_COUNT; i++) {
cheryl_he 0:fc22cf8cc478 173 tele_linescan[i] = data[i];
cheryl_he 0:fc22cf8cc478 174 }
cheryl_he 0:fc22cf8cc478 175 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 176 Writing to the objects flags the new data to be transmitted on the next telemetry IO operation.
cheryl_he 0:fc22cf8cc478 177 \item Regularly call \texttt{Telemetry}'s \texttt{do\_io} operation to transmit any updated data and handle received data (like remote set commands).
cheryl_he 0:fc22cf8cc478 178 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 179 telemetry_obj.do_io();
cheryl_he 0:fc22cf8cc478 180 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 181 \textbf{Note that the code may not be thread-safe.} It scans through all the telemetry data objects, checking for and writing updated values to the output stream.
cheryl_he 0:fc22cf8cc478 182 \item Telemetry data objects may have their values set remotely, though they will not latch (i.e. setting it on the embedded-side causes the remotely-set value to be overwritten). As an example, if \texttt{tele\_motor\_pwm} is not set anywhere else, this code allows the motor PWM duty cycle to be set remotely.
cheryl_he 0:fc22cf8cc478 183 \begin{lstlisting}[language=C++]
cheryl_he 0:fc22cf8cc478 184 PwmOut MotorOutput(PTA4);
cheryl_he 0:fc22cf8cc478 185 telemetry::Numeric<float> tele_motor_pwm(telemetry_obj, "motor", "Motor PWM", "%DC", 0);
cheryl_he 0:fc22cf8cc478 186 ...
cheryl_he 0:fc22cf8cc478 187 telemetry_obj.do_io(); // remote set commands to tele_motor_pwm are processed here
cheryl_he 0:fc22cf8cc478 188 MotorOutput.write(tele_motor_pwm);
cheryl_he 0:fc22cf8cc478 189 \end{lstlisting}
cheryl_he 0:fc22cf8cc478 190 \item Note that you may continue to use the UART to transmit other data (like \texttt{printf}s) as long as this is not done during the middle of a \texttt{Telemetry} \texttt{do\_io} operation or contains the start-of-frame sequence (\texttt{0x05 0x39}).
cheryl_he 0:fc22cf8cc478 191 \end{itemize}
cheryl_he 0:fc22cf8cc478 192
cheryl_he 0:fc22cf8cc478 193 \section{Receive-side Quick Start Guide}
cheryl_he 0:fc22cf8cc478 194 All the receive-side code is contained in (repository base)\texttt{/client-py}.
cheryl_he 0:fc22cf8cc478 195 \subsection{Plotter}
cheryl_he 0:fc22cf8cc478 196 Run the plotter by going into (repository base)\texttt{/client-py} and running \texttt{python plotter.py} and passing in the serial port, baud rate (optional, defaults to 38400), independent variable (optional, defaults to \texttt{time}), and independent variable timespan (optional, defaults to 10000). The arguments list can be obtained through running \texttt{python plotter.py --help}
cheryl_he 0:fc22cf8cc478 197
cheryl_he 0:fc22cf8cc478 198 The plotter must be running when the header is transmitted, otherwise it will fail to decode the data packets (and notify you of such). The plotter will automatically reinitialize upon receiving a new header.
cheryl_he 0:fc22cf8cc478 199
cheryl_he 0:fc22cf8cc478 200 This simple plotter graphs all the data against a selected independent variable (like time). Numeric data is plotted as a line graph and array-numeric data is plotted as a waterfall / spectrograph-style graph in real-time. Regular UART data (like from \texttt{printf}s) is also written to the console in real-time. All received data, including from \texttt{printf}s, is logged to a CSV. A new CSV is created each time a new header packet is received, with a timestamped filename.
cheryl_he 0:fc22cf8cc478 201
cheryl_he 0:fc22cf8cc478 202 You can double-click a plot to inspect its latest value numerically and optionally remotely set it to a new value.
cheryl_he 0:fc22cf8cc478 203
cheryl_he 0:fc22cf8cc478 204 If you feel really adventurous, you can also try to mess with the code to plot things in different styles. For example, the plot instantiation function from a received header packet is in \texttt{subplots\_from\_header}. The default just creates a line plot for numeric data and a waterfall plot for array-numeric data. You can make it do fancier things, like overlay a numerical detected track position on the raw camera waterfall plot.
cheryl_he 0:fc22cf8cc478 205
cheryl_he 0:fc22cf8cc478 206 \subsection{Console Demo}
cheryl_he 0:fc22cf8cc478 207 The console demo is also in (repository base)\texttt{/client-py} and can be run with \texttt{python console.py}. This simply prints the parsed received packets and can be useful if trying to learn the parser API.
cheryl_he 0:fc22cf8cc478 208
cheryl_he 0:fc22cf8cc478 209 \subsection{Parser Library}
cheryl_he 0:fc22cf8cc478 210 The parser code is in (repository base)\texttt{/client-py/telemetry/parser.py}. No official documentation is currently available, but docstrings are scattered in important places and you can reference the console demo or plotter code.
cheryl_he 0:fc22cf8cc478 211 \\
cheryl_he 0:fc22cf8cc478 212 \\
cheryl_he 0:fc22cf8cc478 213 That's all, folks!
cheryl_he 0:fc22cf8cc478 214 \end{document}