doc: fix typos, add missing links and labels

[jenkicar/rpp-simulink.git] / doc / rpp_simulink.tex

\newcommand{\superscript}[1]{\ensuremath{^{\textrm{\small#1}}}}
\newcommand{\subscript}[1]{\ensuremath{_{\textrm{\small#1}}}}

\documentclass{scrreprt}

\usepackage{graphicx} % images and graphics
\usepackage{paralist} % needed for compact lists
\usepackage[normalem]{ulem} % needed by strike
\usepackage{listings} % required for code blocks
\usepackage[urlcolor=blue,colorlinks=true,hyperfootnotes=false]{hyperref} % links
\usepackage[utf8x]{inputenc}  % char encoding
\usepackage[bottom]{footmisc} % footnotes
\usepackage{todonotes}

% header
\usepackage[top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
\usepackage{float} % To fix images position

% Prettify code documentation
\usepackage{color}
\definecolor{gray97}{gray}{.97}
\definecolor{gray75}{gray}{.75}
\definecolor{gray45}{gray}{.45}
\lstset{ frame=Ltb,
     framerule=0pt,
     aboveskip=0.5cm,
     framextopmargin=3pt,
     framexbottommargin=3pt,
     framexleftmargin=0.4cm,
     framesep=0pt,
     rulesep=.4pt,
     backgroundcolor=\color{gray97},
     rulesepcolor=\color{black},
     %
     stringstyle=\ttfamily,
     showstringspaces = false,
     basicstyle=\small\ttfamily,
     commentstyle=\color{gray45},
     keywordstyle=\bfseries,
     %
     numbers=left,
     numbersep=15pt,
     numberstyle=\tiny,
     numberfirstline = false,
     breaklines=true,
     xleftmargin=20px,
   }

% Spacing
\linespread{1.15} % Lines spacing
\setlength{\plitemsep}{0.5\baselineskip} % List items spacing
\definecolor{deepblue}{RGB}{0,0,61}
\hypersetup{linkcolor=deepblue,}

% Table of content depth
\setcounter{tocdepth}{4}

% Landscape pages
\usepackage{lscape}
\usepackage{pdflscape}

% Change page
\usepackage{changepage}

% Font options
% Sans-serif
% \renewcommand{\familydefault}{\sfdefault}
% Better PDF font
\usepackage{lmodern}

% Multiple columns
\usepackage{multicol}
\usepackage{caption}

\newcommand{\repo}{$\langle$repo$\rangle$}

\begin{document}

% Title
\newcommand{\HRule}{\rule{\linewidth}{0.5mm}}

\begin{titlepage}
\begin{center}

% Upper part of the page
\includegraphics[width=0.70\textwidth]{images/logos.png}\\[1cm]
\textsc{\LARGE Costa Rica Institute of Technology}\\[0.5cm]
\textsc{\LARGE Czech Technical University in Prague}\\[1.5cm]


% Document title
\HRule \\[0.4cm]
{ \huge \bfseries Code generation for automotive rapid prototyping platform using Matlab/Simulink}\\[0.4cm]
\HRule \\[1.5cm]


% Author
\emph{Authors:}\\
Carlos \textsc{Jenkins}\\
Michal \textsc{Sojka}\\[\baselineskip]

\emph{Version:}
\input{version.tex}

\vfill

% Bottom of the page
{\large \today}

\end{center}
\end{titlepage}
% Title end

\tableofcontents

\newpage

\listoffigures

\newpage

\addtolength{\parskip}{\baselineskip} % Paragraph spacing

\chapter{Introduction}
\label{chap-introduction}

This text is a documentation for a Rapid Prototyping Platform (RPP) project. It may serve as a
guideline for development tools installation, Simulink Coder configuration, creation of new models as
well as downloading the resulting firmware to the hardware. It can also be used as a reference for a
testing tool, Matlab Simulink blocks and RPP Matlab Simulink Code generator. The document also
provides an overall description of the hardware design and architecture of its control software.

\section{Background}
\label{sec-background}

The Rapid Prototyping Platform is an ECU (Electronic Control Unit) designed for use in Automotive, thus requirements for Automotive communication interfaces, durable IO ports and analog-digital converters were applied.

The ECU is controlled by TMS570LS5137ZWT MCU, which is an ARM Cortex R4 based microcontroller developed by Texas Instruments. This MCU contains several protective mechanisms (two cores in lockstep, error correction mechanisms for SRAM and Flash memory, voltage monitoring...) to fulfill the requirements for safety critical applications. TODO: add ref to Ti Reference

Besides the right MCU, an operating system is necessary for nontrivial applications. The RPP board runs FreeRTOS, which is an opensource operating system with real-time kernel, aimed not only on embedded systems. The FreeRTOS provides an API for creation and managing multiple tasks, scheduler, memory manager, semaphores, queues, mutexes, timers and lots of other features wich can be used in the applications. TODO: add ref to FreeRTOS pages

Even with the operating system it is quite hard and non-intuitive to control the hardware directly. That is the point when abstraction comes in the play. RPP software is made of several layers implementing from the bottom to the top driver to the hardware itself, hardware abstraction for common functionality on different hardware and final API which is easy for the user to use. The whole thing, the operating system and the control software, can be compiled as a library and easily used in any project. More details about the library can be found in Chapter \ref{chap-c-support-library}.

Because humans make mistakes and in safety critical applications any mistake can cause damage, looses of money or in the worst case even death of other people, the room for making mistakes has to be as small as possible. An approach called Model-based development has been introduced. In Simulink  the application is developed as a model made of blocks connected together. Every block implements some functionality. For example one block receives a voltage from an analog-digital converter, provides the value as an input to another block which implements some clever algorithm and the product is passed as an input to another block, which sends the value as a CAN message to some other MCU. The final model can be simulated and tested even before the real hardware exists. Finally a C code is generated from the model by a Simulink Code Generator. The code can be compiled by the MCU compatible compiler and downloaded to the MCU Flash memory on the device. Because every block and code generated from the block has to pass a series of tests during their development, the room for making mistakes during the application development has significantly decreased and developers can focus on the functionality instead of the hardware and control software implementation. More information about Code generation can be found in Chapter \ref{chap-simulink-coder-target}.

\section{Software architecture}
\label{sec-software-architecture}
The RPP control software, also called RPP library, is structured into 5 layers, described in Figure \ref{fig-layers}, with the following guidelines:

\begin{compactitem}
\item Top-down dependency only. No lower layer depends on anything from upper layers.
\item 1-1 layer dependency only. The top layer depends exclusively on the bottom layer, not on any
  lower level layer (except for a couple of exceptions).
\item Each layer should provide a unified layer interface (\textsc{rpp.h}, \textsc{drv.h}, \textsc{hal.h}, \textsc{sys.h}
  and \textsc{os.h}), so top layers depends on that layer interface and not on individual elements from
  that layer.
\end{compactitem}

\begin{figure}[H]
\begin{center}
\noindent
\includegraphics[width=250px]{images/layers.pdf}
\caption{The RPP library layers.}
\label{fig-layers}
\end{center}
\end{figure}

As a consequence of this division the source code files and interface files are placed in
private directories like \textsc{drv/din.h}. With this organization user applications only needs
to include the top layer interface files (for example \textsc{rpp/rpp\_can.h}) to be able to use the selected library API.

The rest of the section provides basic description of each layer.

\subsection{Operating System layer}
\label{sec-operating-system-layer}
This is an operating system interchangeable layer, containing the FreeRTOS source files. The system can be easily replaced by another version thanks to this layer. For example it is possible to compile the library for Linux (using POSIX version of the FreeRTOS), which can be desirable for some testing. The source files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/os} folder.

Following FreeRTOS versions are distributed:
\begin{description}
        \item[6.0.4\_posix] POSIX version, usable for compilation of the library for Linux system.
        \item[7.0.2] Prefered version of the FreeRTOS, distributed by the Texas Instruments. This version is in use in the current version of the library.
        \item[7.4.0] Newest version distributed by the Texas Instruments.
        \item[7.4.2] Newer version available from FreeRTOS pages. Slightly modified to run on TMS570 MCU.  
\end{description}

\subsection{System Layer} 
\label{sec-system-layer}
This layer contains system files with data types definitions, clock definitions, interrupts mapping, MCU startup sequence, MCU selftests, and other low level code for controlling some of the MCU peripherals. The source files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/rpp/src/sys}, the header files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/rpp/include/sys} folder.

\subsection{HAL abstraction layer}
\label{sec-hal-abstraction-layer}
Hardware Abstraction Layer (HAL) creates an abstraction over the real hardware. For example imagine an IO port with 8 pins. First four pins are connected to the MCU directly to GPIO pins, another four pins are connected to an external integrated circuit, communicating with the MCU via SPI. It would be annoying to have to remember which group is which and to have two sets of control functions for one peripheral. This layer maps every pin of the port to a control function from the System Layer, groups the pins together, names them in a unified style and provides common read, write and configure functions.

As a result, the higher layers do not have to know anything about the wiring of the peripherals, they can just call read, write or configure function with a pin name as a parameter and the HAL handles all the details.

The source files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/rpp/src/hal} and the header files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/rpp/include/hal} folder.

\subsection{Drivers layer} 
\label{sec-drivers-layer}
The Drivers layer contains code for controlling the RPP peripherals. The layer benefits from the lower layers thus it is not too low level, but still there are some peripherals like ADC or H-bridge, which needs some special procedure for initialization and running, that would not be very intuitive for the user. For example the H-bridge needs a watchdog reset task to be started before the bridge is enabled.

The source files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/rpp/src/drv} and the header files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/rpp/include/drv} folder.

\subsection{RPP Layer}
\label{sec-rpp-layer} 
The RPP Layer is the highest layer of the control software. This layer provides the easiest set of functions for every peripheral and requires only basic knowledge about them. For example the H-bridge again from the previous section. The user can call just \textsc{rpp\_hbr\_init()} function to enable the H-bridge and the function calls a sequence of Drivers layer functions to start the Watchdog and configure the peripheral.

The source files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/rpp/src/rpp} and the header files can be found in \textsc{$\langle$rpp\_lib\_root$\rangle$/rpp/include/rpp}.

\section{Hardware description}
\label{sec-hardware-description}

This section provides reference documentation for the RPP board:

%%TODO: operating conditions as a reference to the Ti documentation

\begin{compactitem}
\item Layout description.
\item Connectors pinout.
\item Modules capabilities and features.
\end{compactitem}

\subsection{Layout description}
\label{sec-layout-description}
The RPP board has been designed with strict Automotive standards and safety in mind. The components and pins are placed in sections and wires are routed in a way to avoid any significant electromagnetic interference.

As can be seen on Figure \ref{board_photo}, the high power output logic is placed in the top left corner, the low power output logic is placed on the bottom left corner, while the communication logic is placed on the top right corner.  In the middle there is the only one button available, the reset button and below it is placed the TMS570 MCU itself. In the bottom right corner there are components of analog inputs.

\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=300px]{images/board-photo.png}
\caption{The RPP board (signal connector missing).}
\label{board_photo}
\end{center}\end{figure}


\subsection{Connectors pinout}
\label{sec-connector-pinout}
The pinout of the board, described by the Figure \ref{pinout}, follows the layout described in the previous section. The side connectors for communication (24 pins), signals (56 pins) and power (24 pins) are automotive approved humidity resistant connectors.
\begin{figure}[H]
\advance\leftskip-1cm
\noindent
\includegraphics[width=530px]{images/pinout.pdf}
\caption{The RPP connectors pinout.}
\label{pinout}
\end{figure}

\subsection{Modules description}
\label{sec-modules-description}
This section enumerates the capabilities of the hardware modules from Software perspective. The block diagram of the modules can be seen in Figure \ref{blocks}.
\begin{figure}[H]
\advance
\leftskip-1cm
\noindent
\includegraphics[width=500px]{images/blocks.pdf}
\caption{The RPP layer modules.}
\label{blocks}
\end{figure}

\subsubsection{Logic IO}
\label{sec-logic-io}

\paragraph{Digital Inputs (DIN)}
\label{par-digital-inputs}
\begin{compactitem}
\item 16 pins available on Signal Connector.
\item Pins 8-15 status can be read via GPIO using configurable threshold. \newline{}
  Pins 8-11 use variable threshold B and pins 12-15 use variable threshold A.
\item Variable threshold is a DAC chip MCP4922.
\item All pins are read at once via SPI (fixed threshold) using chip MC33972.
\item 0-7 are programmable pins and can be set to pull-up or pull-down. 8-15 are pull-down only.
\item All pins can be set to be active or tri-stated.
\item All pins can be set to trigger interrupt.
\item On-line diagnostic of broken wire.
\end{compactitem}

\paragraph{Digital Outputs (LOUT)}
\label{par-digital-outputs}
\begin{compactitem}
\item 8 pins available on Signal Connector.
\item Pins for logic output only, up to 100mA.
\item All pins are set at once using a chip through SPI.
\end{compactitem}

\paragraph{Analog Input (ADC)}
\label{par-analog-input}
\begin{compactitem}
\item 12 channels available.
\item Differential inputs, thus 24 pins available on Signal Connector.
\item Range for 0-20 volts.
\item 12 bits resolution.
\item Using CPU ADC.
\end{compactitem}

\paragraph{Analog Output (DAC)}
\label{par-analog-output}
\begin{compactitem}
\item 4 pins available on Signal Connector.
\item Output range is 0-12 volts.
\item Using 2 x MCP4922 DACs controlled using SPI.
\item Resolution is 12 bits. But because of amplification and voltage reference not all range is used.
\end{compactitem}

\subsubsection{Power Output}
\label{sec-power-output}
\paragraph{H-Bridge (HBR)}
\label{par-hbr}
\begin{compactitem}
\item 1 port (2 pins) available on Power Connector.
\item Communication is done through SPI.
\item H-Bridge can be enabled or disabled.
\item Current direction can be set.
\item PWM control with 1\% resolution change of the duty cycle.
\item Port can drive load up to 10A.
\end{compactitem}

\paragraph{Power Output (MOUT)}
\label{par-power-output}
\begin{compactitem}
\item 6 pins available on Power Connector.
\item Pins can drive a load up to 2A. Push/Pull.
\item Pins are set using 6 CPU output GPIOs. Diagnostic are read using 6 externally pulled-up
  open-drain input GPIOs.
\item On-line diagnostics. Driver chip will pull-down the corresponding diagnostic pin on the CPU.
\end{compactitem}

\paragraph{High-Power Output (HOUT)}
\label{par-high-power-output}
\begin{compactitem}
\item 6 pins available on Power Connector.
\item Pins can be set ON/OFF.
\item Pins can drive a load up to 10A with PWM.
\item System can read analog values of current flowing (IFBK).
\item System can read diagnostics values (DIAG). Detection of a fault condition.
\end{compactitem}

\subsubsection{Communication}
\label{sec-communication}
\paragraph{CAN bus (CAN)}
\label{par-can}
\begin{compactitem}
\item 3 ports available (CAN uses differential signaling) thus 6 pins are available on Communication
  connector.
\item High speed.
\item Recover from error.
\item Detection of network errors.
\end{compactitem}

\paragraph{Local Interconnect Network (LIN)}
\label{par-lin}
\begin{compactitem}
\item 2 ports/pins available on Communication Connector.
\item Only first port can be used when using the SCI. Second port is shared with SCI.
\end{compactitem}

\paragraph{FlexRay (FR)}
\label{par-flexray}
\begin{compactitem}
\item 2 ports available. FlexRay uses differential signaling thus 4 pins are available on
  Communication Connector.
\end{compactitem}

\paragraph{Serial Comm. Interface (SCI)}
\label{par-sci}
\begin{compactitem}
\item 1 port available inside the box on SCI connector (4 pins).
\item Variable baud rate. Tested on 9600 and 115200.
\item RS232 standard compatible.
\end{compactitem}

\paragraph{Ethernet (ETH)}
\label{par-eth}
\begin{compactitem}
\item 1 port available. Standard Ethernet connector available inside box.
\end{compactitem}

\subsubsection{Data storage/logging}
\label{sec-data-storage}
\paragraph{External Memory SD-RAM (SDR)}
\label{par-external-memory}
\begin{compactitem}
\item 64MB (currently installed) external RAM used for logging. Maximal supported capacity is 256MB.
\item Memory test routine available with test Software.
\end{compactitem}

\paragraph{SD Card (SDC)}
\label{par-sd-card}
\begin{compactitem}
\item Standard SD-Card connector or microSD connector available inside box.
\item Communication done using SPI.
\end{compactitem}

\section{Document structure}
\label{sec-document-structure}
The general layout of this document is as follows:

\chapter{Getting started}
\label{chap-getting-started}

\section{Software requirements}
\label{sec-software-requirements}
The RPP software stack was developed to be functional on both platforms Windows and Linux. Despite of older and newer versions of the software and tools might work as well, usage of the following versions is suggested:

\subsection{Linux environment} 
\label{sec-linux-environment}
\begin{itemize}
        \item Debian based 64b Linux distribution (Debian 7.0 or Ubuntu 14.4 for example).
        \item Kernel version 3.11.0-12.
        \item GCC version 4.8.1
        \item GtkTerm 0.99.7-rc1
        \item Ti Code Composer Studio 5.5.0.00077
        \item Matlab 2013b 64b
        \item Doxygen 1.8.4 (optionaly, see Section \ref{sec-compiling-api-documentation})
        \item Uncrustify 0.59 (optionally, see Section \ref{sec-compilation}).
\end{itemize}

\subsection{Windows environment}
\label{sec-windows-environment}
\begin{itemize}
        \item Windows 7 Enterprise 64b Service Pack 1.
        \item C/C++ compiler from Windows SDK
        \item Bray Terminal v1.9b
        \item Ti Code Composer Studio 5.5.0.00077
        \item Matlab 2013b 64b
        \item Doxygen 1.8.4 (optionaly, see Section \ref{sec-compiling-api-documentation})
        \item Uncrustify 0.59 (optionally, see Section \ref{sec-compilation}).
\end{itemize}

\section{Software and tools} 
\label{sec-software-and-tools}

\subsection{TI Code Composer Studio}
\label{sec-ti-ccs}
Code Composer Studio (CCS) is the official Integrated Development Environment (IDE) for developing
applications for Texas Instruments embedded processors. CCS is multiplatform Software based on
Eclipse Open Source IDE.

CCS includes Texas Instruments Code Generation Tools (CGT) (compiler, linker, etc). Simulink code
generation requires the CGT to be available in the system, and thus, even if no library development
will be done or the IDE is not going to be used CCS is still required.

%% TODO: Zjistit podminky pro distribuci dokumentu
You can find documentation for CGT compiler in \textsc{\repo/ref/armcl.pdf} and for CGT archiver in
\textsc{\repo/ref/armar.pdf}.

The version used in this project is the 5.5.0.00077.

\subsubsection{Installation on Linux} 
\label{sec-installation-on-linux}
Download CCS for Linux from:

        \begin{quotation}
\url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
        \end{quotation}

Once downloaded, add executable permission to the installation file and launch the installation by executing it. Installation must be done as root in order to install a driver set.

\lstset{language=bash}
\begin{lstlisting}
chmod +x ccs_setup_5.5.0.00077.bin
sudo ./ccs_setup_5.5.0.00077.bin
\end{lstlisting}

After installation the application can be executed with:

\lstset{language=bash}
\begin{lstlisting}
cd <ccs>/ccsv5/eclipse/
./ccstudio
\end{lstlisting}

The first launch on 64bits systems might fail. This can happen because CCS5 is 32b application and thus requires 32bits libraries:

\lstset{language=bash}
\begin{lstlisting}
sudo apt-get install libgtk2.0-0:i386 libxtst6:i386
\end{lstlisting}

If the application crashes with a segmentation fault edit file:

\lstset{language=bash}
\begin{lstlisting}
nano <ccs>/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_<version>/plugin_customization.ini
\end{lstlisting}

And change key \textsc{org.eclipse.ui/showIntro} to false.

\subsubsection{ Installation on Windows }
\label{sec-installation-on-windows}
The installation for Windows is more straightforward than the previous procedure for Linux.

Download CCS for Windows from:

        \begin{quotation}
\url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
        \end{quotation}

Once downloaded run the ccs\_setup\_5.5.0.00077.exe and install the CCS.

\subsubsection{ First launch } 
\label{sec-first-launch}
If another licence is not available, choose ``FREE License - for use with XDS100 JTAG Emulators" from the licensing options. Code download for the board is using that particular hardware.

\subsection{Matlab/Simulink}
\label{sec-matlab-simulink}
Matlab Simulink is a set of tools, runtime environment and development environment for Model-Based applications development, simulations and generation code for target platforms.
Supported Matlab Simulink version is R2013b for 64 bits Linux and Windows.

\subsection{GtkTerm and Bray Terminal}
\label{sec-gtkterm-bray-terminal}
Most of the interaction with the board is done through a RS-232 serial connection. The terminal Software used for communication is called GtkTerm for Linux and Bray terminal for Windows.

To install GtkTerm execute:

\lstset{language=bash}
\begin{lstlisting}
sudo apt-get install gtkterm
\end{lstlisting}

The Bray Terminal does not require any installation and the executable file is available at 

\begin{quotation}
\url{https://sites.google.com/site/terminalbpp/}
\end{quotation}

\subsection{C Compiler}
\label{sec-c-compiler}
In order to be able to compile Matlab Simulink blocks S-functions a C language compiler has to be available on the development system.

For Linux a GCC 4.8.1 compiler is recommended and can be installed with a command

\lstset{language=bash}
\begin{lstlisting}
sudo apt-get install gcc
\end{lstlisting}

For Windows, the C/C++ compiler is a part of Windows SDK, which installation file is available at 

\begin{quotation}
\url{http://www.microsoft.com/en-us/download/details.aspx?id=8279}
\end{quotation}

\section{Code Composer Studio usage}
\label{sec-code-composerpstudio-usage}

\subsection{Opening of existing project}
\label{sec-openning-of-existing-project}
The project opening procedure is similar to standard Eclipse project opening.

\begin{enumerate}
        \item Launch Code Composer Studio
        \item Select \textsc{File$\rightarrow$Import}
        \item In the dialog window select \textsc{Code Composer Studio$\rightarrow$Existing CCS Eclipse project} as an import source as depicted in Figure \ref{fig-import-project}.
        \item In the next dialog window click on \textsc{Browse} button and find the root directory of the project.
        \item Select the requested project in the \textsc{Discovered project} section so that the result looks like in Figure \ref{fig-select-project}.
        \item Click on \textsc{Finish} button.
\end{enumerate}

\begin{center}
        \includegraphics[width=350px]{images/import_project.png}
        \captionof{figure}{Import project dialog}
        \label{fig-import-project}
\end{center}

\begin{center}
        \includegraphics[width=350px]{images/select_project.png}
        \captionof{figure}{Select project dialog}
        \label{fig-select-project}
\end{center}

\subsection{Creating new project}
\label{sec-creating-new-project}
In \textsc{\repo/rpp/lib/apps/} there are two RPP based
applications, \textsc{helloworld} and \textsc{helloworld\_posix}, that are
already configured for the RPP Library. It is advised that new applications use this project as a
foundation.

To create a new application copy this directory and rename it. Now open files \textsc{.project},
\textsc{.cproject} and \textsc{.ccsproject} (if available) and change any occurrence of the work \textsc{helloworld}
with the name of your project. Use lower case ASCII letters and underscores only.

\textbf{Steps to configure a new CCS (ARM, using CGT) RPP application:}

\begin{compactenum}
\item Create a new CCS project. \newline{}
\noindent\includegraphics[width=400px]{images/base_1.png}
\item Create a normal folder \textsc{include}.
\item Create a source folder \textsc{src}.
\item Add common \textsc{.gitignore} to the root of that project:
\lstset{language=}
\begin{lstlisting}
Debug
Release
.settings/*
\end{lstlisting}
\newpage
\item Add new variable \textsc{RPP\_LIB\_ROOT} and point to this repository branch root.\newline{}
\noindent\includegraphics[width=400px]{images/base_2.png}
\item Add \textsc{rpp-lib.lib} static library to linker libraries and add \textsc{RPP\_LIB\_ROOT} to the library
  search path.\newline{}
\noindent\includegraphics[width=400px]{images/base_3.png}
\newpage
\item Configure linker to retain \textsc{.intvecs} from RPP static library.\newline{}
\noindent\includegraphics[width=350px]{images/base_4.png}
\item Configure compiler to include local includes, OS includes for TMS570 and RPP includes, in that
  order\todo{Add lwip include paths as well}.\newline{}
\noindent\includegraphics[width=350px]{images/base_5.png}
\newpage
\item Configure compiler to allow GCC extensions.\newline{}
\noindent\includegraphics[width=400px]{images/base_6.png}
\item Import and link (\underline{do not copy!}) linker file and board upload descriptor.\newline{}
\noindent\includegraphics[width=200px]{images/base_7.png}
\end{compactenum}

\textbf{Steps to configure a new GCC (x86(\_64)) RPP simulated application:}

\begin{compactenum}
\item Create a new managed C project that uses Linux GCC toolchain.
\item Create a source folder \textsc{src}. Link all files from original CCS application to this folder.
\item Create a normal folder \textsc{include}. Create a folder \textsc{rpp} inside of it.
\item Add common \textsc{.gitignore} to the root of that project:
\lstset{language=}
\begin{lstlisting}
Debug
Release
.settings/*
\end{lstlisting}
\newpage
\item Add new variable \textsc{RPP\_LIB\_ROOT} and point to this repository branch root.\newline{}
\noindent\includegraphics[width=400px]{images/base_posix_1.png}
\item Configure compiler to include local includes, CCS application includes, OS includes for POSIX and
  RPP includes, in that order.\newline{}
\noindent\includegraphics[width=400px]{images/base_posix_2.png}
\newpage
\item Add \textsc{rpp} and \textsc{pthread}to linker libraries and add \textsc{RPP\_LIB\_ROOT} to the library search
  path.\newline{}
\noindent\includegraphics[width=400px]{images/base_posix_3.png}
\end{compactenum}

\textbf{In general any RPP application uses the layout/template:}

\begin{enumerate}
\item Include RPP library header file. You may also include only a selected modules to save space.
\lstset{language=c++}
\begin{lstlisting}
#include "rpp/rpp.h"
\end{lstlisting}

You may not want to include the whole library to save space and compile time. In this case you may
include only those modules, that you want to use. Inclusion selected modules only requires two more
header files to be included as well: base.h and, in case sci is used for printing, rpp/sci.h.
\begin{lstlisting}
#include "rpp/hbr.h" /* We want to use H-bridge */
#include <base.h>       /* This is a necessary base header file of the rpp library. */
#include "rpp/sci.h" /* This is needed, because we are using rpp_sci_printf in following examples. */
\end{lstlisting}

\newpage
\item Create one or as many FreeRTOS task function definitions as required. Those tasks should use
  functions from this library.
\lstset{language=c++}
\begin{lstlisting}
void my_task(void* p)
{
    static const portTickType freq_ticks = 1000 / portTICK_RATE_MS;
    portTickType last_wake_time = xTaskGetTickCount();
    while (TRUE) {
        /* Wait until next step */
        vTaskDelayUntil(&last_wake_time, freq_ticks);
        rpp_sci_printf((const char*)"Hello RPP.\r\n");
    }
}
\end{lstlisting}

\item Create the main function that will:
 \begin{itemize}
 \item Initialize the RPP board. If you have included only selected modules in step 1, initialize only
   those modules by calling their init functions, for example rpp\_hbr\_init\(\).
 \item Spawn the tasks the application requires. Refer to FreeRTOS API for
   details.
 \item Start the FreeRTOS Scheduler. Refer to FreeRTOS API for details.
 \item Catch if idle task could not be created.
+
\lstset{language=c++}
\begin{lstlisting}
void main(void)
{
    /* In case whole library is included: */
        /* Initialize RPP board */
        rpp_init();
    /* In case only selected modules are included: */
        /* Initialize HBR */
            rpp_hbr_init();
        /* Initialize sci for printf */
        rpp_sci_init();
        /* Enable interrups */
        _enable_IRQ();

    /* Spawn tasks */
    if (xTaskCreate(my_task, (const signed char*)"my_task",
            512, NULL, 0, NULL) != pdPASS) {
        #ifdef DEBUG
        rpp_sci_printf((const char*)
            "ERROR: Cannot spawn control task.\r\n"
        );
        #endif
        while (TRUE) { asm(" nop"); }
    }

    /* Start the FreeRTOS Scheduler */
    vTaskStartScheduler();

    /* Catch scheduler start error */
    #ifdef DEBUG
    rpp_sci_printf((const char*)
            "ERROR: Problem allocating memory for idle task.\r\n"
        );
    #endif
    while (TRUE) { asm(" nop"); }
}
\end{lstlisting}

 \end{itemize}
\item Create hook functions for FreeRTOS:
 \begin{itemize}
 \item \textsc{vApplicationMallocFailedHook()} allows to catch memory allocation errors.
 \item \textsc{vApplicationStackOverflowHook()} allows to catch if a task overflows it's
   stack.
+
\lstset{language=c++}
\begin{lstlisting}
#if configUSE_MALLOC_FAILED_HOOK == 1
/**
 * FreeRTOS malloc() failed hook.
 */
void vApplicationMallocFailedHook(void) {
    #ifdef DEBUG
    rpp_sci_printf((const char*)
            "ERROR: manual memory allocation failed.\r\n"
        );
    #endif
}
#endif


#if configCHECK_FOR_STACK_OVERFLOW > 0
/**
 * FreeRTOS stack overflow hook.
 */
void vApplicationStackOverflowHook(xTaskHandle xTask,
                                   signed portCHAR *pcTaskName) {
    #ifdef DEBUG
    rpp_sci_printf((const char*)
            "ERROR: Stack overflow : \"%s\".\r\n", pcTaskName
        );
    #endif
}
#endif
\end{lstlisting}

\newpage
 \end{itemize}
\end{enumerate}


\subsection{Running software on the HW}
\label{sec-running-software-on-hw}
\subsubsection{Code Composer Studio Project}
\label{sec-ccs-run-project}
When the application is distributed as a CCS project, you have to open the project in the CCS as described in the Section \ref{sec-openning-of-existing-project}. Once the project is opened and built, it can be easily downloaded to the target hardware with the following procedure:

\begin{enumerate}
        \item Connect the Texas Instruments XDS100v2 USB emulator to the JTAG port (see Figure \ref{pinout}, port 1).
        \item Connect a USB cable to the XDS100v2 USB emulator and the development computer.
        \item Plug in the power supply.
        \item In the Code Composer Studio click on the \textsc{Run$\rightarrow$Debug}. The project will  be optionaly built and the download process will start. The Code Composer Studio will switch into debug mode, when the download is finished.
        \item Run the program by clicking on the \textsc{Run} button, with the green arrow.
\end{enumerate}

\subsubsection{Binary File}
\label{sec-binary-file}
If the application is distributed as a binary file, without source codes and CCS project files, you can download and run just the binary file by creating a new empty CCS project and configuring the debug session according the following procedure:

\begin{enumerate}
        \item In Code Composer Studio click on \textsc{File$\rightarrow$New$\rightarrow$CCS Project}.
        \item In the dialog window, type in a project name, for example myBinaryLoad, Select \textsc{Device variant} (ARM, Cortex R, TMS570LS3137, Texas Instruments XDS100v2 USB Emulator) and select project template to \textsc{Empty Project}. The filled dialog should look like on the Figure \ref{fig-new-empty-project}
        \item Click on the \textsc{Finish} button and new empty project will be created.
        \item In the \textsc{Project Explorer} click on the project with a right mouse button and in the context menu select \textsc{Debug as$\rightarrow$Debug configurations}.
        \item Click on a button \textsc{New launch configuration}
        \item Rename the New\_configuration, for example to myConfiguration.
        \item Select configuration target file by clicking the \textsc{File System} button, finding and selecting the TMS5703137.ccxml file. The result should look like on the Figure \ref{fig-debug-conf-main-diag}.
        \item On the \textsc{program} pane select the binary file you want to download to the board. Click on the \textsc{File System} button, find and select the binary file. Rpp-test-sw.out for example. The result should look like on the Figure \ref{fig-debug-conf-program-diag}.
        \item You may also tune the target configuration like in the Section \ref{sec-target-configuration}.
        \item Finish the configuration by clicking on the \textsc{Apply} button and download the code by clicking on the \textsc{Debug} button. You can later invoke the download also from the \textsc{Run$\rightarrow$Debug} CCS menu. You may not need to create more Debug configurations and CCS empty project as you can easily change the binary file in the Debug configuration to load different binary file.
\end{enumerate}

\begin{center}
        \includegraphics[width=350px]{images/new_empty_project.png}
        \captionof{figure}{New empty project dialog}
        \label{fig-new-empty-project}
\end{center}

\begin{center}
        \includegraphics[width=350px]{images/debug_configuration_main.png}
        \captionof{figure}{Debug Configuration Main dialog}
        \label{fig-debug-conf-main-diag}
\end{center}

\subsubsection{Target configuration}
\label{sec-target-configuration}
Default target configuration erases the whole Flash memory, before downloading the code. This is however not needed in most cases. You may disable this feature by the following procedure:
\begin{enumerate}
        \item Right click on the project name in the \textsc{Project Browser}
        \item Select \textsc{Debug as$\rightarrow$Debug Configurations}
        \item In the dialog window select \textsc{Target} pane.
        \item In the \textsc{Flash Settings}, \textsc{Erase Options} select \textsc{Necessary sectors only}.
        \item Save the configuration by clicking on the \textsc{Apply} button and close the dialog.
\end{enumerate}

\begin{center}
        \includegraphics[width=350px]{images/debug_configuration_program.png}
        \captionof{figure}{Debug Configuration Program dialog}
        \label{fig-debug-conf-program-diag}
\end{center}

\section{Matlab Simulink usage}
\label{sec-matlab-simulink-usage}

\subsection{Configuring Simulink for RPP}
\label{sec-configuration-simulink-for-rpp}
\begin{enumerate}
\item Download and install CCS for Linux:

Details on how to setup CCS are available in Section \ref{sec-ti-ccs}.

\item Install RPP Target:

Open Matlab and type on command window:

\lstset{language=Matlab}
\begin{lstlisting}
cd <repo>/rpp/rpp/
rpp_setup
\end{lstlisting}

This will launch the RPP setup script. This script will ask the user to provide the path to the CCS
compiler root directory (the directory where \textsc{armcl} binary is located), normally:

\begin{verbatim}
<ccs>/tools/compiler/arm_5.X.X/
\end{verbatim}

This script will, among other things, ask the user to provide the location of the armcl parent
directory, infer and save some relevant CCS paths, add paths to Matlab path and build S-Function
blocks for user's architecture (using Matlab's mex command line tool).

\item Create a new model or load a demo:

Demos are located on \textsc{\repo/rpp/demo} or you can start a new model and configure target to RPP.
For new models see \htmladdnormallink{Target Reference}{\#target\_reference} section below.
\end{enumerate}


\subsection{Working with demo models}
\label{sec-openning-demo-models}
The demo models are available from the directory \textsc{\repo/rpp/demos}. To access the demo models for reference or for downloading to the RPP board you have to change the directory to the one, containing the desired demo. For example to open the cantransmit demo you have to type these commands into the Matlab command line:

\begin{lstlisting}[language=Matlab]
cd <rpp-simulink-root>/rpp/demos
open('cantransmit.slx')
\end{lstlisting}

The same procedure can be used to open any other models.

\subsection{Creating new model}
\label{sec-crating-new-model}
\begin{enumerate}
\item Open or create a model you want to generate code from.
\item Make sure that the model is configured (\textsc{Simulation $\rightarrow$
  Model Configuration Parameters}) as described later in this section.
\item From Matlab command window change the current directory to where
  you want your generated code to appear, e.g.:
\begin{lstlisting}[language=Matlab]
cd /tmp/my-code
\end{lstlisting}
  The code will be generated in a subdirectory of that directory. The
  name of the subdirectory will be \textsc{<model>\_rpp}, where
  \textsc{model} is the name of the Simulink model.
\item Generate the code by choosing \textsc{Code $\rightarrow$ C/C++ Code
  $\rightarrow$ Build Model}.
\end{enumerate}

If you want to run the model on the RPP board, see Section \ref{sec-running-model-on-hw}.

The new Simulink model needs to be configured in the following way:

\begin{compactitem}
\item Solver (Figure \ref{fig-solver}):
 \begin{compactitem}
 \item Options: \emph{Fixed-step, discrete}
 \item Tasking mode set to \textit{SingleTasking}.
   \begin{figure}
     \centering
     \includegraphics[width=400px]{images/simulink_solver.png}
     \caption{Solver settings}
         \label{fig-solver}
\end{figure}
 \end{compactitem}
\item Diagnostics $\rightarrow$ Sample Time (Figure~\ref{fig-sample-time-settings}):
 \begin{compactitem}
 \item Disable warning source block specifies -1 sampling time. It's ok for the source blocks to run
   once per tick.
   \begin{figure}
     \centering
     \includegraphics[width=400px]{images/simulink_diagnostics.png}
     \caption{Sample Time settings}
         \label{fig-sample-time-settings}
\end{figure}
\end{compactitem}
\item Code generation (Figure~\ref{fig-code-gen-settings}):
 \begin{compactitem}
 \item Set to \textsc{rpp.tlc}.
   \begin{figure}
     \centering
     \includegraphics[width=400px]{images/simulink_code.png}
     \caption{Code Generation settings}
         \label{fig-code-gen-settings}
\end{figure}
\end{compactitem}
\end{compactitem}


\subsection{Running model on the HW}
\label{sec-running-model-on-hw}
To run the model on the target RPP hardware you have to enable the download feature and build the model by following this procedure:
\begin{enumerate}
        \item Open the model you want to run (See Section \ref{sec-openning-demo-models}.)
        \item Click on \textsc{Simulation$\rightarrow$Model Configuration Parameters}.
        \item In the \textsc{Code Generation$\rightarrow$RPP Options} pane check \textsc{Download compiled binary to RPP} checkbox.
        \item Click on \textsc{OK} button, connect the target HW to the computer like in the Section \ref{sec-ccs-run-project} and build the model. If the build ends with a success, the download process will start and once the downloading is finished, the application will run immediatelly.
\end{enumerate}

The code downloading is supported for Windows and Linux development systems. If you are using Linux, you may also try to use the OpenOCD by checking Use OpenOCD to download the compiled binary checkbox in addition. Refer 

\begin{verbatim}
http://rtime.felk.cvut.cz/hw/index.php/TMS570LS3137#OpenOCD_setup_and_Flashing
\end{verbatim}
fore more information about the OpenOCD configuration.

  Note: You should end the Code Composer Studio debug session before
  downloading the generated code to the RPP board. Otherwise the
  download fails.

 
\section{Configuring serial interface}
\label{sec-configuration-serial-interface}
The main interface for communicating with the RPP board is the serial interface. The application may define its own interface settings, but the following settings is the default one:
\begin{itemize}
        \item Baudrate: 115200
        \item Parity: none
        \item Bits: 8
        \item Stopbits: 1
        \item Flow control: none
\end{itemize}

Use GtkTerm in Linux or Bray Terminal for accessing the serial interface. See Section \ref{sec-hardware-description} for reference about the position of the serial interface connector on the RPP board.

\section{Bug reporting}
\label{sec-bug-reporting}

% TODO: implement

\chapter{C Support Library}
\label{chap-c-support-library}

This chapter describes the implementation of a C support library (RPP Library) to provide an overall
insight for future development.

\section{Description}
\label{sec-description}
The RPP C Support Library (also called RPP library) defines the API for communication with the board. It includes drivers and operating system and is designed from the board user perspective and exposes a simplified high-level API to handle the board's peripheral modules in a safe manner. The library is compiled as a static library with the name rpp-lib.lib and can be found in \textsc{\repo/rpp/lib}.

The RPP library can be used in any project, where the RPP hardware support is required and is also used in two modules, described later in this document. The Command line testing tool, described in Chapter \ref{chap-rpp-test-software} and Simulink Coder target, described in Chapter \ref{chap-simulink-coder-target}.

For details about the library architecture, refer the Section \ref{sec-software-architecture} in Chapter \ref{chap-introduction}  

\section{API development guidelines}
\label{sec-api-development-guidlines}

The following are the development guidelines used for developing the RPP API:

\begin{compactitem}
\item User documentation should be placed in header files, not in source code, and should be Doxygen
  formatted using autobrief. Documentation for each function present is mandatory.
\item Function declarations on the headers files is for public functions only. Do not declare
  local/static/private functions on the header.
\item Documentation on source code files should be non-doxygen formatted and intended for developers,
  not users. Documentation here is optional and at the discretion of the developer.
\item Always use standard data types for IO when possible. Use custom structs as very last resort.
\item Use prefix based functions names to avoid clash. The prefix is of the form \textsc{[layer]\_[module]\_},
  for example \textsc{rpp\_din\_update()} for the update function of the DIN module in the RPP Layer.
\item Be very careful about symbol export. Because it is used as a static library the modules should
  not export any symbol that is not intended to be used (function) or \textsc{extern}'ed (variable) from
  application. As a rule of thumb declare all global variables as static.
\item Only the RPP Layer symbols are available to user applications. All information related to lower  layers is hidden for the application. This is accomplished by the inclusion of the rpp.h or rpp\_\{mnemonic\}.h file on the implementations files only and never on the interface files. Never expose any other layer to the application or to the whole system below the RPP layer. In other words, never \textsc{\#include "foo/foo.h"} in any RPP Layer interface file.
\end{compactitem}

\section{Coding style}
\label{sec-coding-style}
In order to keep the code as clean as possible, a unified coding style should be followed by any contributor to the code. The RPP library project is prepared for a usage of a program named Uncrustify.

The Uncrustify program checks the code and fixes those lines that does not match the coding style. However keep in mind that the program is not perfect and sometimes some lines can be modified even when the suggested coding style has been followed. This does not causes problems as long as the contributor follows the committing procedure described in next paragraph.

When contributing to the code, the contributor should learn the current coding style from the existing code. When a new feature is implemented, before committing to the repository, a command :
\lstset{language=bash}
\begin{lstlisting}
make uncrustify
\end{lstlisting}
in a Linux terminal should be called. This command fixes any coding style errors. After that all changes can be committed.

\section{Subdirectory  content description}
\label{sec-subdirectory-content-description}
\begin{description}
        \item[librpp.a and rpp-lib.lib] Version controlled RPP static libraries.

The first one is for POSIX simulation, the second one for Simulink models and other ARM/TMS570 applications. This files are placed here by the Makefile, when the library is built.

        \item[apps/] Demo applications related to the RPP library.

This include the CCS studio project for generation of the static library and the a test suite. The test suit in this directory does not match the test suite mentioned later in Chapter 5 and those two suits are going to be merged in the future. Also other demo Hello World like applications are included as a reference about how to create a TMS570 application.
        \item[os/] OS layers directory. See OS interchangeable layer for more information.
        \item[rpp/] Main directory for the RPP Library.
        \item[rpp/doc/] Documentation directory for the RPP Library.
        \item[rpp/TMS570LS3137.ccxml] Descriptor for code download.

This file is used by all the projects including the Simulink RPP Target for code download. It is
configured to use the Texas Instruments XDS100v2 USB Emulator.
        \item[rpp/TMS570LS313xFlashLnk.cmd] CGT Linker command file.

This file is used by all applications linked for the board, including the Simulink models, static
library and test suite. It includes instructions for the CGT Linker on where to place sections
and size of some sections.
        \item[rpp/include/\{layer\} and rpp/src/\{layer\}] Interface files and implementations files for given \textsc{\{layer\}}. See Section \ref{sec-software-architecture} in Chapter \ref{chap-introduction} for details on the RPP Layer.
        \item[rpp/include/rpp/rpp.h] Main library header file.

To use this library with all its modules, just include this file and this file only. Also, before using any library function please call \textsc{rpp\_init()} function for hardware initialization.

        \item[rpp/include/rpp/rpp\_\{mnemonic\}.h] Header file for \textsc{\{mnemonic\}} module.

This files includes function definitions, pin definitions, etc, specific to \{mnemonic\} module. See Section \ref{sec-api-development-guidlines}.

You may include only selected rpp\_\{mnemonic\}.h header files and call the specific rpp\_\{mnemonic\}\_init functions, instead of the rpp.h and rpp\_init function, if you want to use only a subset of the library functions.

        \item[rpp/src/rpp/rpp\_\{mnemonic\}.c] Module implementation.

Implementation of \textsc{rpp\_\{mnemonic\}.h}'s functions on top of the DRV library.
        \item[rpp/src/rpp/rpp.c] Implementation of library-wide functions.

\end{description}

\section{Compilation}
\label{sec-compilation}

The RPP Library can be compiled as a static library for ARM using a Code Composer Studio project or for x86 Linux using an Eclipse project. After the compilation, as part of the build process, both procedures will automatically update the version-controlled static libraries in the library root.

For the compilation of the library as a static library open the Code Composer studio project for the rpp-lib (see Section \ref{sec-openning-of-existing-project}) and build the project. As a result of the build process, if successful, a \textsc{rpp-lib.lib} file will appear in the library root directory.

\begin{compactitem}
\item \textsc{rpp-lib.lib}, static library for ARM using TI naming scheme.
\item \textsc{librpp.a}, static library for x86(\_64) using standard Linux naming scheme.
\end{compactitem}

Because compilation of the libraries in Eclipse IDE can be error
prone, there is a \textsc{Makefile} that allows to compile the
libraries from the Linux command line:

\begin{lstlisting}[language=bash]
cd <library-root>
make
\end{lstlisting}

This option is available for Linux based development systems only.

Note that this Makefile still requires the Code Composer Studio to be
installed.

The relevant aspects for compiling and linking an application using the static libraries are:
\begin{itemize}
        \item \textbf{ARM compilation using CCS for the RPP board:}
        \begin{compactitem}
                \item Include headers files of the OS for which the library was compiled against. At the time of this
          writing the OS is FreeRTOS 7.0.2. See Section \ref{sec-software-architecture}
                \item Include header files for the RPP library or for modules you want to use rpp\_can.h for CAN module for example.
                \item Add library \textsc{rpp-lib.lib} to the linker libraries. The RPP library \textbf{MUST} be looked for
          before Texas Instruments support library \textsc{rtsv7R4\_T\_be\_v3D16\_eabi.lib}.
                \item Configure linker to retain \textsc{.intvecs} section from RPP Library:\newline{}
          \textsc{--retain="rpp-lib.lib$\langle$sys\_intvecs.obj$\rangle$(.intvecs)"}
                \item Use the provided linker command file \textsc{TMS570LS313xFlashLnk.cmd}.
        \end{compactitem}
        \item \textbf{x86(\_64) compilation using GCC for Simulation:}
        \begin{compactitem}
                \item Include headers files of the OS for Simulation. At the time of this writing the OS is POSIX
          FreeRTOS 6.0.4.
                \item Include header files for the RPP library or for modules you want to use (rpp\_can.h for CAN module for example).
                \item Add library \textsc{librpp.a} to the linker libraries.
                \item Add \textsc{pthread} to the linker libraries.
        \end{compactitem}
\end{itemize}

As an important note, all the models compiled using Simulink will link against \textsc{rpp-lib.lib}.
When compiling a Simulink model, neither Simulink nor the
\textsc{make} invoked during the build process, will update the generated binary
if the model hasn't changed, and then if the source code hasn't changed. Static libraries changes
are not considered for re-compilation and re-linking. If library development is being done and
static library is updated, in order for the Simulink model to generate a newly linked version of
the binary the whole code generation folder needs to be deleted in order to force code generation,
compilation and linking with the new static library.

\section{Compiling API documentation}
\label{sec-compiling-api-documentation}
The RPP Layer is formatted using Doxygen documentation generator. This allows to generate a high
quality API reference. To generate the API reference run in a Linux terminal:

\lstset{language=bash}
\begin{lstlisting}
cd <repo>/rpp/lib/rpp/doc/api
make
xdg-open html/index.html
\end{lstlisting}

The files under \textsc{\repo/rpp/lib/rpp/doc/api/content} are used for the API reference generation
are their name is self-explanatory:

\begin{verbatim}
blocks_map.html
blocks.png
cvut.png
footer.html
main_page.dox
\end{verbatim}

\chapter{Simulink Coder Target}
\label{chap-simulink-coder-target}

The Simulink Coder Target allows to convert Simulink models to C code,
compile it and download to the board.

\section{Introduction}
\label{sec-introduction}

The Simulink RPP Target provides support for C source code generation from Simulink models and
compilation of that code on top of the RPP library and the FreeRTOS operating system. This target
uses Texas Instruments ARM compiler (\textsc{armcl}) included in the Code Generation Tools distributed with
Code Composer Studio, and thus it depends on it for proper functioning.

This target also provides support for automatic download of the compiled binary to the RPP
board.

\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=300px]{images/tlc_process.png}
\caption{TLC code generation process.}
\end{center}\end{figure}

\section{Features}
\label{sec-features}

\begin{itemize}
\item Supports only single tasking.  If multitasking is required, it has to be implemented in a new file \textsc{rpp\_mrmain.tlc} in \textsc{\repo/rpp/rpp/} and \textsc{rpp\_file\_process.tlc} has to be edited to use that file, when multitasking is selected.
\item No External mode support
\item Custom compiler options, available via OPTS variable in \emph{Make command} at \emph{Code Generation} tab (see Figure \ref{fig-code-gen-settings}). For example \textsc{make\_rtw OPTS="-O0 -g"}.

\end{itemize}

\section{RPP Options pane}
\label{sec-rpp-target-options}

The RPP Target includes the following configuration options, all of them configurable per model
under  \textsc{Code Generation} \noindent$\rightarrow$ \textsc{RPP Options}:

\begin{itemize}
\item \textbf{C system stack size}: this parameter is passed directly
  to the linker for the allocation of the stack. Note that this stack
  is used only for initializing the application and FreeRTOS. Once
  everything is initialized, another stack is used by the generated
  code. See below. Default value is 4096.

\item \textbf{C system heap size}:
  \label{sec-rpp-target-options-heap-size} this parameter is passed
  directly to the linker for the allocation of the heap. Currently,
  the heap is not used, but will be used by the external mode in the future. Note that FreeRTOS uses its own heap whose size is independent of this parameter.
\item \textbf{Model step task stack size}: this parameter will be passed to the \textsc{xTaskCreate()} that
  creates the task for the model to run. In a Simulink model there are always two tasks:
 \begin{itemize}
 \item The worker task. This task is the one that executes the model
   step. This task requires enough stack memory to execute the step.
   If your model does not run, it might be caused by too small stack.
   The memory needed for the stack depends on the size and structure
   of the model.
 \item The control task. This task controls when the worker task should execute and controls overruns.

 \end{itemize}
\item \textbf{Download compiled binary to RPP}: if set, this option will download the generated binary to
  the board after the model is successfully built. Note that this option is unaware of the option
  \textit{Generate code only} in the \textit{Code Generation} options panel, so it will try to download even if
  only source code has been generated, failing graciously or uploading an old binary laying around
  in the build directory. This option calls the \textsc{rpp\_download.m} script, which is in turn a
  wrapper on the \textsc{loadti.sh}, \textsc{loadti.bat} and \textsc{loadopenocd.sh} script. More information on the \textsc{loadti.sh}
  script can be found in:
\begin{verbatim}
<css>/ccs_base/scripting/examples/loadti/readme.txt
http://processors.wiki.ti.com/index.php/Loadti
\end{verbatim}

  The \textsc{loadti.sh} and\textsc{loadti.bat} script will close after the download of the generated program, leaving the loaded program running.

  The \textsc{loadopenocd.sh} script will close after the download of the generated program as well, but the program will be stopped.
  In order to test the loaded program a manual reset of the board is required.

\item \textbf{Download compiled binary to SDRAM}: This feature is not yet implemented for the simulink target.

\item \textbf{Use OpenOCD to download the compiled binary}: This option switches from Ti loading script \textsc{loadti.sh}
  to OpenOCD script \textsc{loadopenocd.sh}. The benefit of using OpenOCD, besides that it is open source
  software, is much shorter loading time. More information about the right OpenOCD version and its installation
  can be found at:
\begin{verbatim}
http://rtime.felk.cvut.cz/hw/index.php/TMS570LS3137#OpenOCD_setup_and_Flashing
\end{verbatim}
This feature is available for Linux system only.

\item \textbf{Print model metadata to SCI at start}: if set this option will print a message to the Serial
  Communication Interface when the model start execution on the board. This is very helpful to
  identify the model running on the board. The message is in the form:
\begin{verbatim}
`model_name' - generated_date (TLC tlc_version)
\end{verbatim}

  For example:
\begin{verbatim}
`hbridge_analog_control' - Wed Jun 19 14:10:44 2013 (TLC 8.3 (Jul 20 2012))
\end{verbatim}
\end{itemize}

\section{Subdirectory  content description}
\label{sec-subdirectory-content-description}
This section describes the directories of the Simulink Coder. If you are interested in particular file, refer the description at the beginning of the file.
\begin{description}
        \item[doc/] Contains the sources of the documentation, you are now reading.
        \item[refs/] Contains third party references, which license allows the distribution.
        \item[rpp/blocks] Contains the TLC files, which defines the blocks for the Matlab Simulink and \textsc{rpp\_lib.slx}, which is the Simulink RPP Library, containing all the Simulink blocks for RPP.
        \item[rpp/blocks/tlc\_c]Contains the templates for C code generation from the Matlab Simulink model.
        \item[rpp/demos] Contains demo models, which purpose is to serve as a reference for the usage and for testing.
        \item[rpp/lib] Contains the C Support Library. See Chapter \ref{chap-c-support-library}.
        \item[rpp/loadopenocd] Contains download scripts for Linux support of the OpenOCD, for code downloading to the target.
        \item[rpp/loadti] Contains download scripts for Linux and Windows support for code downloading to the target, using Texas Instruments CCS code downloader.
        \item[rpp/rpp] Contains set of support script for the Code Generator.
\end{description}

\section{Block Library Overview}
\label{sec-block-library-overview}
The Simulink Block Library is a set of blocks that allows Simulink models to use board IO and 
communication peripherals. The available blocks are summarized in
Table~\ref{tab:block-lib-status} and more detailed description is
given in Section~\ref{sec-blocks-description}.

\begin{table}
\begin{center}\begin{tabular}{lp{5cm}lll}
\textbf{Category} & \textbf{Name} & \textbf{Status} & \textbf{Mnemonic} & \textbf{Header} \\
\input{block_table.tex}
System blocks & High-Power output block & \textsc{X} & \textsc{[HOUT]} & \textsc{rpp\_hout.h} \\
 & LIN receive block & \textsc{X} & \textsc{[LINR]} & \textsc{rpp\_lin.h} \\
 & LIN send msg block & \textsc{X} & \textsc{[LINS]} & - Idem - \\
 & Ethernet receive block & \textsc{X} & \textsc{[ETHR]} & \textsc{rpp\_eth.h} \\
 & Ethernet send msg block & \textsc{X} & \textsc{[ETHS]} & - Idem - \\
 & SDRAM write block & \textsc{X} & \textsc{[SDRW]} & \textsc{rpp\_sdr.h} \\
 & Stack overflow detected block & \textsc{X} & \textsc{[TRSO]} & - None - \\
 & Malloc Failed detected block & \textsc{X} & \textsc{[TRMF]} & - None - \\
\end{tabular}\end{center}

  \caption{Block library overview}
  \label{tab:block-lib-status}
\end{table}

\subsection{Blocks implementation}
\label{sec-blocks-implementation}
All of the blocks are implemented as a C Mex S-Function coded by hand. In this section the 
approach taken is briefly explained.

\subsubsection{C MEX S-Functions}
\label{sec-c-mex-functions}
 \begin{compactitem}
 \item C : Implemented in C language. Other options are Fortran and Matlab language itself.
 \item MEX: Matlab Executable. They are compiled by Matlab - C compiler wrapper called MEX.
 \item S-Function: System Function, as opposed to standard functions, or user functions.
 \end{compactitem}

A C-MEX S-Function is a structured C file that implements some mandatory and optional  callbacks for a specification of a number of inputs, outputs, data types, parameters, rate, validity checking, etc.
A complete list of callbacks can be found in:
        \begin{quotation}
\htmladdnormallink{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}
        \end{quotation}

The way a C-MEX S-Function participates in a Simulink simulation is shown on the diagram \ref{fig-sfunctions-process}:

\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=250px]{images/sfunctions_process.png}
\caption{Simulation cycle of a S-Function.}
\label{fig-sfunctions-process}
\end{center}\end{figure}

In general, the S-Function can perform calculations, inputs and outputs for simulation. Because 
the RPP blocks are for hardware peripherals control and IO the blocks are 
implemented as pure sink or pure source, the S-Function is just a descriptor of the block and does not perform any calculation and does not provide any input or output for simulations. 

The implementation of the S-Functions in the RPP project has following layout:

\begin{itemize}
\item Define S-Function name \textsc{S\_FUNCTION\_NAME}.
\item Include header file \textsc{header.c}, which in connection with \textsc{trailer.c} creates a miniframework for writing S-Functions.
\item In \textsc{mdlInitializeSizes} define:
        \begin{itemize}
        \item Number of \textit{dialog} parameter.
        \item Number of input ports.
                \begin{compactitem}
                \item Data type of each input port.
                \end{compactitem}
        \item Number of output ports.
                \begin{compactitem}
                \item Data type of each output port.
                \end{compactitem}
        \item Standard options for driver blocks.
        \end{itemize}
\item In \textsc{mdlCheckParameters}:
        \begin{itemize}
        \item Check data type of each parameter.
        \item Check range, if applicable, of each parameter.
        \end{itemize}
\item In \textsc{mdlSetWorkWidths}:
        \begin{compactitem}
        \item Map \textit{dialog} parameter to \textit{runtime} parameters.
                \begin{itemize}
                \item Data type of each \textit{runtime} parameter.
                \end{itemize}
        \end{compactitem}
\item Define symbols for unused functions.
\item Include trailer file \textsc{trailer.c}.
\end{itemize}

The C-MEX S-Function implemented can be compiled with the following command:

\lstset{language=bash}
\begin{lstlisting}
<matlabroot>/bin/mex sfunction_{mnemonic}.c
\end{lstlisting}

As noted the standard is to always prefix S-Function with \textsc{sfunction\_} and use lower case 
mnemonic of the block.

Also a script called \textsc{compile\_blocks.m} is included. The script that allows all \textsc{sfunctions\_*.c} to be fed to the \textsc{mex} compiler so all S-Functions are compiled at once. To use this script, in Matlab do:

\lstset{language=Matlab}
\begin{lstlisting}
cd <repo>/rpp/blocks/
compile_blocks()
\end{lstlisting}

\subsubsection{Target Language Compiler files}
\label{sec-target-language-compiler-files}

In order to generate code for each one of the S-Functions, every S-Function implements a TLC file
for \textit{inlining} the S-Function on the generated code. The TLC files describe how to 
generate code for a specific C-MEX S-Function block. They are programmed using TLC own language and 
include C code within TLC instructions, just like LaTeX files include normal text in between LaTeX 
macros.

The standard for a TLC file is to be located under the \textsc{tlc\_c} subfolder from where the 
S-Function is located and to use the very exact file name as the S-Function but with the \textsc{.tlc}
extension: \textsc{sfunction\_foo.c} \noindent$\rightarrow$ \textsc{tlc\_c/sfunction\_foo.tlc}

The TLC files implemented for this project use 3 hook functions in particular (other are available, 
see TLC reference documentation):
\begin{itemize}
\item \textsc{BlockTypeSetup}: \newline{}
  BlockTypeSetup executes once per block type before code generation begins.
  This function can be used to include elements required by this block type, like includes or
  definitions.
\item \textsc{Start}: \newline{}
  Code here will be placed in the \textsc{void $\langle$modelname$\rangle$\_initialize(void)}. Code placed here will
  execute only once.
\item \textsc{Outputs}: \newline{}
  Code here will be placed in the \textsc{void $\langle$modelname$\rangle$\_step(void)} function. Should be used to 
  get the inputs o a block and/or to set the outputs of that block.
\end{itemize}

The general layout of the TLC files implemented for this project are:
\begin{itemize}
\item In \textsc{BlockTypeSetup}: \newline{}
  Call common function \textsc{\%$<$RppCommonBlockTypeSetup(block, system)$>$} that will include the 
  \textsc{rpp/rpp\i\_mnemonic.h} header file (can be called multiple times but header is included only once).
\item \textsc{Start}: \newline{}
  Call setup routines from RPP Layer for the specific block type, like HBR enable, DIN pin setup, 
  DAC value initialization, SCI baud rate setup, among others.
\item \textsc{Outputs}: \newline{}
  Call common IO routines from RPP Layer, like DIN read, DAC set, etc. Success of this functions
  is checked and in case of failure error is reported to the block using ErrFlag.
\end{itemize}

C code generated from a Simulink model is placed on a file called \textsc{$\langle$modelname$\rangle$.c} along with other support files in a folder called \textsc{$\langle$modelname$\rangle$\_$\langle$target$\rangle$/}. For example, the source code generated for model \textsc{foobar} will be placed in current Matlab directory \textsc{foobar\_rpp/foobar.c}.

The file \textsc{$\langle$modelname$\rangle$.c} has 3 main functions:
\begin{compactitem}
\item \textsc{void $\langle$modelname$\rangle$\_step(void)}: \newline{}
  This function recalculates all the outputs of the blocks and should be called once per step. This
  is the main working function.
\item \textsc{void $\langle$modelname$\rangle$\_initialize(void)}: \newline{}
  This function is called only once before the first step is issued. Default values for blocks IOs
  should be placed here.
\item \textsc{void $\langle$modelname$\rangle$\_terminate(void)}: \newline{}
  This function is called when terminating the model. This should be used to free memory of revert 
  other operations made on the initialization function. With current implementation this function
  should never be called unless an error is detected and in most models it is empty.
\end{compactitem}

\subsection{Blocks description}
\label{sec-blocks-description}

This section describes each one of the Simulink blocks present in the Simulink RPP Library, illustrated in Figure \ref{fig-block-library}:

\begin{figure}[H]
\advance
\leftskip-1cm
\noindent
\includegraphics[width=530px]{images/block_library.png}
\caption{Simulink RPP Block Library.}
\label{fig-block-library}
\end{figure}

% Include automatically generated documentation
% TODO: the block_desc is badly generated
\input{block_desc.tex}

\section{Demos}
The Simulink RPP Demo Library is a set of Simulink models that use blocks from the Simulink RPP
Block Library and generates code using the Simulink RPP Target.

This demos library is used as a test suite for the Simulink RPP Block Library but they are also
intended to show basic programs built using it. Because of this, the demos try to use more than one
type of block and more than one block per block type.

In the reference below you can find a complete description for each of the demos.

\subsection{Analog pass-through}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_analog_passthrough.png}
\caption{Analog Passthrough Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}
This demo will read analog input 1 and write it to analog output 1.

In laboratory the minimum read value for analog input a 0 volts is 107. The maximum read at 12
volts is 2478. The map subsystem will map the input domain (ADC)\textsc{[110, 2400]} to the output domain
(DAC)\textsc{[0, 4095]}.


\subsection{Analog sinewave}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_analog_sinewave.png}
\caption{Analog Sinewave Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}
This demo will generate a sinewave on analog output 1. The frequency
of the sine wave is 10Hz and sampling rate is set to
1000Hz (driven from Simulink step of 1ms, same as operating system). Amplitude is set to use DAC
full range [0-4095] which means output amplitude will be [0-12] volts.

The Software oscilloscope shown should match an external one connected to DAC 1.

Note that the driver configuration of the MCP4922 is set to unbuffered (which should eventually
be changed to buffered) and thus the last resolution millivolts are lost.


\subsection{CAN transmit}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_cantransmit.png}
\caption{Example of the usage of the CAN blocks for RPP.}
\end{center}\end{figure}

\textbf{Description:}

Demostrates how to use CAN Transmit blocks in order to:

\begin{compactenum}
\item Send unpacked data with data type uint8, uint16 and uint32.
\item Send single and multiple signals packed into CAN\_MESSAGE by CAN Pack block.
\item Send a message as extended frame type to be received by CAN Receive configured to receive both, standard and extended frame types. 
\end{compactenum}

Demostrates how to use CAN Receive blocks in order to:

\begin{compactenum}
\item Receive unpacked data of data types uint8, uint16 and uint32.
\item Receive and unpack received CAN\_MESSAGE by CAN Unpack block.
\item Configure CAN Receive block to receive Standard, Extended and both frame types.
\item Use function-call mechanism to process received messages
\end{compactenum}

\subsection{CAN demo}

\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_can_demo.png}
\caption{CAN bus demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo demonstrates simple processing of received messages.

\subsection{Digital pass-through}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=400px]{images/demo_digital_passthrough.png}
\caption{Digital Pass-through Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo will directly pass the digital values read on DIN [1-8] to LOUT [1-8], and thus acting
as a digital pass-through or gateway.

Also note that all the ErrFlag are aggregated on a global ErrFlag.

\subsection{Echo char}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_echo_char.png}
\caption{Echo Character Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo will echo twice (print back) any character received through the Serial Communication
Interface (9600-8-N-1).

Note that the send subsystem is implemented a as \textit{triggered} subsystem and will execute only
if data is received, that is, Serial Receive output is non-negative. Negative values are errors.


\subsection{H-bridge analog control}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_hbridge_analog_control.png}
\caption{H-Bridge Analog Control Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo will read values from the analog input, map them, and control the H-Bridge. This allows
a motor connected to the H-Bridge to be controlled with a potentiometer connected to Analog Input 1.

Setting the potentiometer to output around 6 volts will stop the motor. Less (or greater) than 6
volts will trigger the motor in one sense (or in the other sense) and speed proportional with 1\%
resolution.

In laboratory the minimum read value for analog input is 107 at 0 volts. The maximum read at 12 volts
is 2478. The map subsystem will map the input domain (ADC)\textsc{[110, 2400]} to the output domain
(HBR)\textsc{[-1.0, 1.0]}.


\subsection{H-bridge digital control}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_hbridge_digital_control.png}
\caption{H-Bridge Digital Control Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo toggle the H-Bridge from stop to full speed in one direction using digital input 1.
So basically is a ON/OFF switch on DIN 1 for a motor connected on the HBR. Note the data type
conversion because the output of the DIN is a boolean and the input to the HBR is a double.

\subsection{H-bridge sine wave control}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=300px]{images/demo_hbridge_sinewave_control.png}
\caption{H-Bridge Sinewave Control Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo will generate a sine wave to control the H-Bridge. Sine wave is one period per 20
seconds or 0.05Hz. Sampling rate is 20Hz or 100 samples per 1/4 of period (for 1\% speed
resolution change).

Note that the Software oscilloscope should is not the output of the H-Bridge, the H-Bridge will
change current sense and the duty cycle of the pulse that drive it (PWM), it does not output
analog values. The Software oscilloscope just shows what the input to the HBR block is.

\subsection{Hello world}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_hello_world.png}
\caption{Hello World Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo will print \textsc{"Hello Simulink"} to the Serial Communication Interface (9600-8-N-1) one
character per second. The output speed is driven by the Simulink model step which is set to one
second.

\subsection{IRC input}
\begin{figure}[H]\begin{center}

\noindent
\includegraphics[width=450px]{images/demo_irc_input.png}
\caption{LED Blink Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo is printing IRC sensor (connected to DIN10 and DIN11) value to the Serial Communication
Interface (115200-8-N-1) with six values to one line.

\subsection{LED blink}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_led_blink.png}
\caption{LED Blink Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This the simplest demo of all that shows the basics of using the RPP target and blocks. The
goal of this demo is to show the configuration of the model (not shown on the picture above),
that is, how the RPP Simulink Coder Target is setup, general model setup and step setup.

This demo will toggle each second a LED connected on LOUT 1. The timing is set by the Simulink
model step which is set to 1 second.

\subsection{LED blink all}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=350px]{images/demo_led_blink_all.png}
\caption{LED Blink All Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo will toggle all LEDs connected to the LOUT port. Even outputs pins will be negated.
Toggle will happen each second. The timing is driven by Simulink model step configuration that
is set to 1 second. All blocks ErrFlags are aggregated into one global ErrFlag.

\subsection{Log analog input}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=450px]{images/demo_log_analog_input.png}
\caption{Log Analog Input Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo will log once per second the value read on the analog input 1. User can read the log
using the SCI logging integrated command processor (9600-8-N-1). Logging block ID set to 1. The
timing is driven by Simulink model step configuration that is set to 1 second.

\subsection{Power toggle}
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=300px]{images/demo_power_toggle.png}
\caption{Power Toggle Simulink demo for RPP.}
\end{center}\end{figure}

\textbf{Description:}

This demo will toggle the power output once per second. If an error is detected on at least one of
the outputs a generic error message is printed to the serial line. The timing is driven by Simulink
model step configuration that is set to 1 second. Power outputs can drive a load up to 2A, so please
take into account required safety considerations.

\subsection{Simulink Demo board}
Model for demo board has 6 subsystems. Every subsystem will be described separately.
\begin{figure}[H]\begin{center}
\noindent
\includegraphics[width=0.8\textwidth]{images/demo_board-connection_scheme.pdf}
\caption{Demo board connection and usage scheme.}
\end{center}\end{figure}

\subsubsection{Potentiometer regulation of motor speed}
This is example of driving motor with input signal. Motor can be rotated in various speed in both directions and stopping motor means setting potentiometer to half of its range. Potentiometer value is also transmitted through CAN.

\subsubsection{Color music}
This is showing abilities of RPP board to generate analog signals. Bargraphs on demo board are showing value of analog outputs. Speed of change can be changed with potentiometer and in one case is used motor 2 IRC. There are five different modes. Three of them are derived from sinus and rest of them are counter value and direct control. Modes can be changed with black button. First mod selected after board start is fifth.
\begin{enumerate}
\item Sinus signal is sequential delayed by 10 steps for second and third bargraph.
\item Sinus signal on second bargraph is shifted by 120° and on third one is shifted by 240°.
\item Sinus signal for second and third bargraphs are shifted same as in previous mode, but as counter value is used IRC value with appropriate divider no potentiometer value.
\item Visualizing counter value which speed is changed with potentiometer.
\item Potentiometer value is passed to all bargraphs with appropriate multiplier.
\end{enumerate}

\subsubsection{Buttons and LEDs}
This is example of digital input/output. LEDs on demo board can be driven with four different subprograms. These subprograms can be changed with red button and are influenced with green and blue buttons.
\begin{enumerate}
\item One LED is always ON and others are OFF. Every 0.1 sec is neighborhood LED switched on and previous one is switched off. With buttons you can change direction.
\item Same as previous mode, but change is not done after 0.1 sec but only when button is pressed.
\item In this mode you can record message in Morse code (max 64 chars including spaces) and after delay it is repetitively replayed. To record message use green button as dash and blue button as dot.
\item Simple game in which you must determine if light is moving left or right and press green or blue button according to it. Speed of movement is increasing and in case of wrong answer or long delay is game ends with lights flashing.
\end{enumerate}

\subsubsection{IRC to CAN}
IRC value from Motor 2 is sent every tenth step via CAN2 with message ID 0x4.

\subsubsection{CAN receive -- Button press emulation}
You can simulate press of all four buttons by sending message through CAN2 to board with message ID 0x0 and value according to button number.

\subsubsection{Configuration and error handling}
RPP supports some basic runtime error handling. Every block can set its error flag, all these error flags are joined in this demo together and when some problem is detected CAN2 message of ID 0x10 is transmitted. Also in case of board overrun (exhaustion of time quanta) is transmitted message through CAN2 with ID 0x11.\\
When model is build without external mode, errors are also printed to SCI.

\subsubsection{Full list of CAN communication}
The board produces CAN frames with the following IDs:
\begin{itemize}
\item 0x05: Potentiometer 1 value.
\item 0x06: Potentiometer 2 value.
\item 0x08: Selected mod of color music.
\item 0x09: Active subprogram of buttons and LEDs.
\item 0x10: Transmitted only in case of error flag of some block, error code.
\item 0x11: Transmitted only in case of board overrun, no data.
\end{itemize}
The board reacts to CAN frames with following IDs:
\begin{itemize}
\item 0x00: Simulate button press, accepts value 1--4.
\end{itemize}

\chapter{Command line testing tool}
\label{chap-rpp-test-software}
The \textsc{rpp-test-suite} is a RPP application developed testing and direct control of the RPP hardware. The test suite implements a command processor, which is listening for a commands and prints some output related to the commands on the serial interface. The command processor is modular and each peripheral has its commands in a separated module.

The command processor is implemented in <rpp-test-sw>/cmdproc and commands modules are implemented in <rpp-test-sw>/commands directory.

The application enables a command processor using the SCI at \textbf{115200-8-N-1}. When the software starts, the received welcome message and prompt should look like:

\begin{verbatim}
TODO: FILL
\end{verbatim}

Type in command help for a complete list of available command, or help command for a description of concrete command.

\section{Commands description}

% Generated by html2tex: Version 2.7 of February 6, 2012.
% Written by F.J. Faase.  http://www.iwriteiam.nl/

% html: Beginning of file: `doc.html'

\subsection{adcread}

\label{f0}
Read values from ADC inputs

\subsubsection{Command syntax}

\begin{verbatim}  adcread\end{verbatim}

\subsubsection{Description}


This command reads values corresponding to analog voltages on ADC inputs 1-12 and prints them as decimal numbers as well as converted to Volts.

\subsubsection{Example}

\begin{verbatim}  --> adcread
 ADC1  2332 lsb ~ 11.66 V
 ADC2   107 lsb ~  0.54 V
 ADC3   108 lsb ~  0.54 V
 ADC4   107 lsb ~  0.54 V
 ADC5   108 lsb ~  0.54 V
 ADC6   111 lsb ~  0.56 V
 ADC7   110 lsb ~  0.55 V
 ADC8   109 lsb ~  0.55 V
 ADC9   107 lsb ~  0.54 V
 ADC10  107 lsb ~  0.54 V
 ADC11  110 lsb ~  0.55 V
 ADC12  108 lsb ~  0.54 V\end{verbatim}

\subsection{adcread*}


Read a value from a single ADC input

\subsubsection{Command syntax}

\begin{verbatim} adcread<PIN>\end{verbatim}

where \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1 - 12.

\subsubsection{Description}


This command reads the value corresponding to analog voltage on an ADC input and prints it as decimal numbers as well as converted to Volts.

\subsubsection{Example}

\begin{verbatim} --> adcread1
ADC1  2331 lsb ~ 11.66 V\end{verbatim}

\subsection{adcwatch}


Watch the values from ADC inputs

\subsubsection{Command syntax}

\begin{verbatim} adcwatch\end{verbatim}

\subsubsection{Description}


This command reads values corresponding to analog voltages on ADC inputs 1-12 10 times per second and prints them as decimal numbers (in lsb units) as well as converted to Volts. The command is ended by any key.

\subsubsection{Example}

\begin{verbatim} --> adcwatch
ADC Inputs Test [1-12]:
=======================================================================
    1     2     3     4     5     6     7     8     9    10    11    12
 2331   107   108   106   107   110   110   109   107   107   110   109 lsb
11.66  0.54  0.54  0.53  0.54  0.55  0.55  0.55  0.54  0.54  0.55  0.55 V\end{verbatim}

\subsection{canbaudrate\#}


Change baudrate of CAN controller

\subsubsection{Command syntax}

\begin{verbatim} canbaudrate<CONTROLLER>?
canbaudrate<CONTROLLER>:<BAUDRATE>\end{verbatim}

where \texttt{\mbox{$<$}CONTROLLER\mbox{$>$}} is number in range 1-3 and BAUDRATE is number in range 1000-10000000 specifying the baudrate in bits per second.

\subsubsection{Description}


This command is used to set or show the baudrate of a CAN controller. The baudrate shown is the one which will be used by next invocation of the caninit command. The baudrate specified by the command is used to automatic calculation of the CAN controller timing. If you want to specify the timing manually, please use the command cantiming. The automatic calculation might not work properly for some baudrates. In this case you should calculate the timing manually and specify it by the command cantiming.

\subsubsection{Examples}

\begin{verbatim} --> canbaudrate2?
canbaudrate2=500000

--> canbaudrate2:100000\end{verbatim}

\subsection{candump}


Dump all messages received over CAN

\subsubsection{Command syntax}

\begin{verbatim} candump <CONTROLLER>\end{verbatim}

where \texttt{\mbox{$<$}CONTROLLER\mbox{$>$}} is a number in range 1-3.

\subsubsection{Description}


This command prints out all CAN messages received via the specified controller.

IDs are zero-filled to length 3 if a message in the standard frame format is received and to 8 for extended frame format messages.

caninit must be called before using this command.

\subsubsection{Example}

\begin{verbatim} --> candump 2\end{verbatim}

can2 0000FADE \mbox{$[$}2\mbox{$]$} 12 34

\subsection{caninit}


Initialize CAN controllers

\subsubsection{Command syntax}

\begin{verbatim} caninit\end{verbatim}

\subsubsection{Description}


This command (re-)initializes all CAN controllers using current CAN configuration. This configuration can be changed using canbaudrate command.

In the default configuration the baudrate of all CAN controllers i set to 500 kbit/s.

\subsubsection{Example}


--\mbox{$>$} caninit

\subsection{canrpptest}


Test the CAN functions from the RPP library

\subsubsection{Command syntax}

\begin{verbatim} canrpptest\end{verbatim}

\subsubsection{Description}


This command tests all CAN functions in the RPP library. It does those particular tests:

1) Test of the rpp\emph{can}init(), rpp\emph{can}write() and rpp\emph{can}read() functions. At the beginning, the CAN bus is initialized with manually specified and verified CAN bit timing parameters. Then a message is sent on the CAN1 and is received on the CAN2. Finally the received message is compared with the sent one. If the transmissions fails, reception exceeds a timeout or the sent and received messages do not match, the command prints the appropriate error code.2) Test of the CAN bit timing parameters calculation. This test subsequently initializes the CAN bus to a baudrates 125k, 250k and 500k. For each one of them a message is sent on CAN1 and received on CAN2. Finally the received message is compared with the sent one like in a test (1). If the initialization, transmission, reception or comparison fails or if the reception timeout is reached, an appropriate error code is printed. 3) Test of the behavior of transmission request overwriting. The CAN bus is initialized like in the test (1). A message A transmission request is posted on CAN1 by calling rpp\emph{can}write() and right after that another message B transmission request is posted on CAN1 by another call of the rpp\emph{can}write(). A message B is received on CAN2, because the second request came so quickly, that it overwrote the first one. The sent and received messages are compared to verify that the transmission was correct. If the initialization, transmission, reception or comparison fails or if the reception timeout is reached, an appropriate error code is printed. 4) Test of the TX request pending flag detection. The CAN bus is initialized like in the test (1). A message is transmitted on the CAN1 and the test waits for the TX pending flag to be set, which signalizes that there is a message transmission request pending. After the flag has been set, the test waits for its clearance, which means that the message has been sent. The test measures, how many flag test cycles passed, until the flag has been cleared. This value is then presented as a time. At the end, the message is received on the CAN2 and is compared with the sent message for verification. If the initialization, transmission, reception or comparison fails or if timeout is reached while waiting for the flag set/clear or receive timeout is reached, an appropriate error code is printed. 5) Test of the message received (RX) indicator. The CAN bus is initialized like in the test (1). A message is transmitted on the CAN1. The test then waits for the RX indicator to be set, which indicates that a message has been received. The message is picked up by the rpp\emph{can}read(). This should clear the indicator, which is tested. Finally the received messages is compared with the sent one. If the initialization, transmission, reception, message comparison or indicator test fails or if timeout is reached while waiting for the flag set, the appropriate error code is printed.

At the end the CAN bus is reset and left with the configuration from test (1). Those tests assumes the CAN1 and CAN2 to be connected in HW loopback. Any previous configuration is canceled, but is not deleted, so any following call of caninit command will restore the CAN bus to previous configuration.

For error codes description refer please the API documentation for the rpp-test-sw.

\subsubsection{Example}

\begin{verbatim} --> canrpptest\end{verbatim}

This is a test for RPP CAN library functions:Test of simple message transmission and reception. CAN bus Initialization...OK Transmission and reception...OK---Test od automatic CAN bit timing calculation. Baudrate: 125000: OK Baudrate: 250000: OK Baudrate: 500000: OK---Test of transmission request rewritting. CAN bus Initialization...OK TX request rewritting...OK---Test of TX request pending flag detection. CAN bus Initialization...OK TX request pending flag behavioral: OK, time: 256 cycles.---Test of RX indicator. CAN bus Initialization...OK RX indicator behavioral:OK, time: 0 cycles.---Reset the CAN bus. CAN bus Initialization...OK\#\# cansend \#\# Test sending message over CAN

\subsubsection{Command syntax}

\begin{verbatim} cansend <CONTROLLER> <ID> <DATA>\end{verbatim}

where \texttt{\mbox{$<$}CONTROLLER\mbox{$>$}} is number in range 1-3, \texttt{\mbox{$<$}ID\mbox{$>$}} is a valid CAN ID and \texttt{\mbox{$<$}DATA\mbox{$>$}} is 0-8 bytes of data in hexadecimal representation. There may be any number of spaces between the data bytes. \texttt{\mbox{$<$}ID\mbox{$>$}} may be given in octal, decimal or hexadecimal base.

\subsubsection{Description}


This command sends a CAN frame using specified CAN controller.

The caninit command must be called before using this command.

\subsubsection{Example}

\begin{verbatim} --> cansend 2 0x123 DEAD BEEF
Sent: can2      123     [4]     DE AD BE EF\end{verbatim}

\subsection{cantiming\#}


Change timing of CAN controller manually

\subsubsection{Command syntax}

\begin{verbatim} cantiming<CONTROLLER>?
cantiming<CONTROLLER>:<BRP> <PROP_SEG> <PHASE_SEG1> <PHASE_SEG2> <SJW>\end{verbatim}

where: - \texttt{\mbox{$<$}CONTROLLER\mbox{$>$}} is number in range 1-3 - \texttt{\mbox{$<$}BRP\mbox{$>$}} (baudrate prescaler) is number in range 1-65 - \texttt{\mbox{$<$}PROP\_SEG\mbox{$>$}} (length of propagation segment in tQ) is a number in range 1-8 - \texttt{\mbox{$<$}PHASE\_SEG1\mbox{$>$}} (phase buffer segment 1 in tQ) is a number in range 1-8 - \texttt{\mbox{$<$}PHASE\_SEG2\mbox{$>$}} (phase buffer segment 2 in tQ) is a number in range 1-8 - \texttt{\mbox{$<$}SJW\mbox{$>$}} (synchronization jump width in tQ) is a number in range 1-4

\subsubsection{Description}


This command is used to set or show the timing of a CAN controller. The timing shown is the one which will be used by next invocation of the caninit command. The timing configured by this command defines manually the baudrate of the CAN controller. If you want to calculate the timing automaticaly from a baudrate, please use the command canbaudrate.

\subsubsection{Examples}

\begin{verbatim} --> cantiming2?
brp: 17
prop_seg: 4 tQ
phase_seg1: 5 tQ
phase_seg2: 5 tQ
sjw: 4 tQ
sample_pt: 875 ns
error: 0
tQ: 125 ns

--> cantiming2:5 8 7 4 1\end{verbatim}

\subsection{dacpinenable*}


Enable or disable a DAC pin

\subsubsection{Command syntax}

\begin{verbatim} dacpinenable<PIN> <VALUE>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1-4
\item \texttt{\mbox{$<$}VALUE\mbox{$>$}} is a number 0 (disable) or 1 (enable)
\end{itemize}

\subsubsection{Description}


Command for enabling or disabling of a DAC pin.

Command always prints the actual state of the selected pin.

\subsubsection{Example}

\begin{verbatim} --> dacpinenable1 1
dacpinenable1=1\end{verbatim}

Enables pin DAC1 and prints its actual state (which will be 1)

\subsection{dacpinval*}


Set raw value of a DAC register

\subsubsection{Command syntax}

\begin{verbatim} dacpinval<PIN> <VALUE>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1-4
\item \texttt{\mbox{$<$}VALUE\mbox{$>$}} is a number in range 0-4095
\end{itemize}

\subsubsection{Description}


This command writes a raw value to DAC register that controls the DAC output voltage according to the formula described in the datasheet. \texttt{\mbox{$<$}PIN\mbox{$>$}} parameter selects which DAC pin to use.

Command always prints the written raw value of the selected pin. There is no way how to read the value out of the register.

\subsubsection{Example}

\begin{verbatim} --> dacpinval1 4095
dacpinval1 =4095\end{verbatim}

Set pin DAC1 voltage to 12V, and prints the value (4095).

\subsection{dacpinvoltage*}


Set voltage in mV of a DAC pin

\subsubsection{Command syntax}

\begin{verbatim} dacpinvoltage<PIN> <VALUE>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1-4
\item \texttt{\mbox{$<$}VALUE\mbox{$>$}} is a number in range 0-12000
\end{itemize}

\subsubsection{Description}


This command sets the voltage on a DAC pin.

The command always prints the actually set voltage of selected pin. There is no way how to read the value back out of the pin.

\subsubsection{Example}

\begin{verbatim} --> dacpinvoltage1 8000
dacpinvoltage1 =8000\end{verbatim}

Sets pin DAC1 to 8V, prints the actual voltage (8000)
\begin{verbatim} --> dacpinvoltage2 500
dacpinvoltage2 =500\end{verbatim}

Sets pin DAC2 to 500mV, prints actual voltage (500)

\subsection{demomotctrl}


Run motor control demo - reads input and sends it

\subsubsection{Command syntax}

\begin{verbatim} demomotctrl\end{verbatim}

\subsubsection{Description}


This command creates a FlexRay node and starts to read buttons (connected to DIN0 and DIN1) and a potentiometer (ADC1) from a control panel. The read data are sent via FlexRay to the second node, created by running demomotdrive command.

The purpose of this pair of commands is to demonstrate functionality of the FlexRay, ADC, DIN and HBR peripherals.

\subsection{demomotdrive}


Run motor control demo - drives the DC motor

\subsubsection{Command syntax}

\begin{verbatim} demomotdrive\end{verbatim}

\subsubsection{Description}


This command creates a FlexRay node and starts to receive the data from another node created by command demomotctrl. The received data are applied to HBR to control the DC motor.

The purpose of this pair of commands is to demonstrate functionality of the FlexRay, ADC, DIN and HBR peripherals.

\subsection{dinget*}


Read the open/close status of a DIN pin (with the default treshold)

\subsubsection{Command syntax}

\begin{verbatim} dinget<PIN>\end{verbatim}

where PIN is a number in range 0-15

\subsubsection{Description}


The command reads and prints the status of the DIN pin. Value 0 means switch is open, value 1 means switch is closed. The mapping between the DIN voltage and the open/close status depends on the setup of the pin (see dinsetup command).

\subsubsection{Example}

\begin{verbatim} --> dinget1
dinget1 =0\end{verbatim}

DIN1 is in open state.

\subsection{dinsetup*}


Setup DIN pin parameters (Pull up/down, tristate/active, IRQ and wakeup disable/enable)

\subsubsection{Command syntax}

\begin{verbatim} dinsetup<PINS> [A [B [C]]]\end{verbatim}

where
\begin{itemize}
\item PINS is either a number in range 1-16 or a range written as \texttt{\mbox{$<$}min\mbox{$>$}-\mbox{$<$}max\mbox{$>$}}
\item A is an optional value - either 0 (pull down/switch to battery) or 1 (pull up/switch to ground). The default is 1.
\item B is an optional value - either 0 (tri-state) or 1 (active). The default is 0.
\item C is an optional value - either 0 (wake up and IRQ disabled) or 1 (wake up and IRQ disabled enabled). The default is 1.
\end{itemize}

\subsubsection{Description}


The command setups properties of one or more DIN pins as specified by \texttt{\mbox{$<$}PIN\mbox{$>$}}. Pins 0-7 can be set as pull up (switch to ground) or pull down (switch to battery), pins 8-15 are hardcoded as switch to ground. All pins can be set to either tri-state or active state and also can have wake-up function with IRQ activated or not.

The command always prints the final settings of each set pin as ABC. The actual configuration cannot be read out of the pin driver.

\subsubsection{Example}

\begin{verbatim} --> dinsetup1 1 0 0
dinsetup1=100\end{verbatim}

Sets the DIN1 as switch to ground, active and disables IRQ generation.
\begin{verbatim} --> dinsetup2
dinsetup2=101\end{verbatim}

Sets the DIN2 as to the default values i.e. switch to battery, tri-state, wake-up/IRQ enabled.
\begin{verbatim} --> dinsetup0-7 1 1 1
dinsetup0=111
dinsetup1=111
dinsetup2=111
dinsetup3=111
dinsetup4=111
dinsetup5=111
dinsetup6=111
dinsetup7=111\end{verbatim}

Sets the DIN0 through DIN7 as switch to ground, tri-state, wake-up/IRQ enabled.

\subsection{dinwatch}


Watch status of all DIN pins

\subsubsection{Command syntax}

\begin{verbatim} dinwatch\end{verbatim}

\subsubsection{Description}


The command reads and prints the status of DIN pins every 100 milliseconds. Columns 0-15 correspond to open/close status of DIN pins with the default threshold of 4 V, columns A-H represent the logical values of pins DIN8-15 when read with programmable threshold. Pin status (open=0, close=1) depends on the pin setup that can be changed with dinsetup command, programmable threshold can be set with TODO command.

Press any key to end this command.

\subsubsection{Example}

\begin{verbatim} --> dinwatch
Digital Inputs Test [0-15]:
===========================================================
 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15  A  B  C  D  E  F  G  H
 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  1  1  1  1  1  1  1  1\end{verbatim}

\subsection{ethbd}


Examine emac buffer descriptors

\subsubsection{Command syntax}

\begin{verbatim} ethbd\end{verbatim}

\subsubsection{Description}


After startup you use keys to control what will be done.
\begin{itemize}
\item q - quit
\item s - general statistics
\item t - transmit channel status
\item r - receive channel status
\item b - after giving address of bd it prints bd content
\item a - checks consistency of buffer descriptors
\end{itemize}

\subsubsection{Example}

\begin{verbatim} --> ethbd\end{verbatim}

\subsection{ethernet}


Temporary command to test Ethernet communication

\subsubsection{Command syntax}

\begin{verbatim} ethernet\end{verbatim}

\subsubsection{Description}


Command tries to send a few ethernet frames. No real connection or meaningful packets are sent. This only tests, if Ethernet is just working.

\subsection{ethinit}


Post OS startup eth initialization

\subsubsection{Command syntax}

\begin{verbatim} ethinit\end{verbatim}

\subsubsection{Description}


This command finishes autonegotiation of PHY and initialize LwIP stack.

\subsubsection{Example}

\begin{verbatim} --> ethinit\end{verbatim}

\subsection{ethip}


Print current IP address of network interface

\subsubsection{Command syntax}

\begin{verbatim} ethip\end{verbatim}

\subsubsection{Description}


This command reads current IP address, netmask and gateway of network interface and prints these to the output.

\subsubsection{Example}

\begin{verbatim} --> ethip
Address: 192.168.247.1
Netmask: 255.255.255.0
Gateway: 192.168.247.255\end{verbatim}

\subsection{ethlinkstat}


Print current status of ethernet interface

\subsubsection{Command syntax}

\begin{verbatim} ethlinkstat\end{verbatim}

\subsubsection{Description}


This command reads PHY link status assigned to ethernet interface and prints interface name and informs about PHY's status to the output.

\subsubsection{Example}

\begin{verbatim} --> ethlinkstat
et0 : UP

--> ethlinkstat
et0 : DOWN\end{verbatim}

\subsection{ethmac}


Print current MAC address of ethernet interface

\subsubsection{Command syntax}

\begin{verbatim} ethmac\end{verbatim}

\subsubsection{Description}


This command obtains MAC address from ethernet interface structure and prints it to the output.

\subsubsection{Example}

\begin{verbatim} --> ethmac
12:34:56:78:9a:bc\end{verbatim}

\subsection{ethnc}


Start very simple netcat

\subsubsection{Command syntax}

\begin{verbatim}  ethnc <IP> <PORT> [-p <PORT>] [-u] [-m [-t] | -d [-t]] [-c]
 ethnc -l <PORT> [-u] [-m [-t] | -d [-t]] [-c]\end{verbatim}

\subsubsection{Description}


Netcat is a program which allows to communicate using TCP or UDP protocols. First a connection is established by either:
\begin{itemize}
\item connecting to a specified IP address and PORT (without option -l) or by
\item listening for a new connection on a given PORT (with option -l).
\end{itemize}

When no -u option is specified ethnc command works with TCP connections. With -u option UDP communication is used. Listening for connection on UDP means waiting for reception of any UDP datagram.

Once the connection is established the command works in one of the following modes:
\begin{itemize}
\item interactive mode in which received data are forwarded to serial line and data received on serial line are sent to the connection when either new line is encountered or when internal buffer is full,
\item sending of testing data (increasing ASCII formatted numbers) (option -d),
\item looping of incoming data back to the connection's peer (option -m).
\end{itemize}

Note: When trying to use a same local TCP port number multiple times in a row (-l or -p options) there might be several minutes delay before the port is available after closing the previous connection. This situation is singled with ERROR 31.

Other options:
\begin{itemize}
\item -p specifies local port for outgoing connections.
\item -u use UDP protocol instead of the default TCP.
\item -t send and/or receive data in a background thread (works only with -d or -m options).
\item -c stop all running background tasks
\end{itemize}

\subsubsection{Examples}


Listen for incoming TCP connection on local port 2000: --\mbox{$>$} ethnc -l 2000

Connect using TCP to address 192.168.247.15 to remote port 80 using local port 1500: --\mbox{$>$} ethnc 192.168.247.15 80 -p 1500

Send testing data to the remote node: --\mbox{$>$} ethnc -d 192.168.247.2 1025

Loop back all data coming from remote node's UDP port 1025: --\mbox{$>$} ethnc -m -u 192.168.247.2 1025

Wait for a TCP connection on local port 30000 and loop all incoming data back: --\mbox{$>$} ethnc -l 30000 -m

\subsection{fraytestA}


Run the FlexRay test as A node

\subsubsection{Command syntax}

\begin{verbatim} fraytestA [<COUNT>]\end{verbatim}

where \texttt{\mbox{$<$}COUNT\mbox{$>$}} is an optional number of messages to send. The default is 100.

\subsubsection{Description}


The commands creates FlexRay node A and starts sending a message approximately every communication cycle. COUNT messages are sent for the test of the connection. The command should be run with two devices connected by a FlexRay bus and the second device should be running the fraytestB command (it is necessary to run both commands shortly after each other).

When the command transmits a message a character is printed. O means that the message was transmitted correctly, X signals a transmission error. The number of TX errors and successfully transmitted messages is maintained during the test and printed at the end.

\subsection{fraytestB}


Run the FlexRay test as B node

\subsubsection{Command syntax}

\begin{verbatim} fraytestB [<COUNT>]\end{verbatim}

where \texttt{\mbox{$<$}COUNT\mbox{$>$}} is an optional number of messages to receive. The default is 100.

\subsubsection{Description}


The commands creates FlexRay node B and starts receiving a messages. 100 messages should be received. The command should be run with two devices connected by a FlexRay bus and the second device should be running the fraytestA command (it is necessary to run both commands shortly after each other).

When the command receives a message a character is printed. O means that the message was received correctly, X signals an error in data, T means timeout (i.e. no message was received within 63 cycles). The number of RX errors and successfully received messages is maintained during the test and printed at the end.

\subsection{frayxcvrstat\#}


Get the status of a FlexRay transceiver in a human readable form

\subsubsection{Command syntax}

\begin{verbatim} frayxcvrstat<CHN>\end{verbatim}

where CHN is a number in range 1-2

\subsubsection{Description}


The command receives response from a FlexRay transceiver via SPI, and prints in the form of attribute-value table.

\subsubsection{Example}

\begin{verbatim} --> frayxcvrstat1\end{verbatim}

Prints the status of FRAY1 transceiver.

\subsection{frbtabort}


Abort FlexRay communication immediately

\subsubsection{Command syntax}

\begin{verbatim} frbtabort\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_AbortCommunication function from the Autosar specification. The command invokes the FlexRay POC command FREEZE, which means that the communication is stopped immediately. On the opposite side there is a frbthalt command, which stops the communication after the end of the actual communication cycle. To restart the communication, the frbtinit and frbtstart commands have to be called.

\subsubsection{Example}

\begin{verbatim} --> frbtabort
FlexRay node communication aborted.\end{verbatim}

\subsection{frbtallslots}


Enables communication for all frames

\subsubsection{Command syntax}

\begin{verbatim} frbtallslots\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_AllSlots function from the Autosar specification.

The node can be configured to communicate only on key frames by default (as in the case of frbtinitA/B). This command can be used to allow the communication on all configured frames. The command invokes the FlexRay POC command ALL\_SLOTS which enables the communication on all frames. The command can be called after the controller initialization.

\subsubsection{Example}

\begin{verbatim} --> frbtallslots
FlexRay node started communication on all slots.\end{verbatim}

\subsection{frbtcanceltimer*}


Stop the timer

\subsubsection{Command syntax}

\begin{verbatim} frbtcanceltimer<TMID>\end{verbatim}

where \texttt{\mbox{$<$}TMID\mbox{$>$}} is a number (0 or 1) specifying the timer.

\subsubsection{Description}


The command stands for Fr\_CancelAbsoluteTimer function from the Autosar specification. It stops the timer selected by the parameter.

\subsubsection{Example}

\begin{verbatim} --> frbtcanceltimer0
Timer was canceled.\end{verbatim}

\subsection{frbtcanceltx*}


Stop the transmission of the frame

\subsubsection{Command syntax}

\begin{verbatim} frbtcanceltx<FRID>\end{verbatim}

where \texttt{\mbox{$<$}FRID\mbox{$>$}} is a decimal number specifying the ID of the frame for which a buffer has been configured.

\subsubsection{Description}


The command stands for Fr\_CancelTxLPdu function from the Autosar specification. The command finds all buffers assigned to the specified frame ID and reconfigures them to stop transmitting data. The command finishes successfully only if reconfiguration is allowed in message RAM configuration (secureBuffers configuration parameter). Only TX buffers and buffers not used for startup frames can be canceled.

\subsubsection{Example}

\begin{verbatim} --> frbtcanceltx3
Transmission canceled.\end{verbatim}

\subsection{frbtccconfig*}


Print value of a FlexRay cluster and node configuration parameter

\subsubsection{Command syntax}

\begin{verbatim} frbtccconfig<INDEX>\end{verbatim}

where \texttt{\mbox{$<$}INDEX\mbox{$>$}} is an identifier of the parameter.

\subsubsection{Description}


The command stands for Fr\emph{ReadCCConfig function from the Autosar specification. The driver stores the configuration parameters as an array. Each parameter can be indexed and returned by this command. See Autosar specification of the FlexRay driver (http://www.autosar.org/download/R4.1/AUTOSAR}SWS\_FlexRayDriver.pdf), section 8.2.1 for parameter indexes.

\subsubsection{Example}

\begin{verbatim} --> frbtccconfig1
Value = 0x1\end{verbatim}

\subsection{frbtcfgbuf?*}


Configure a message buffer in the user configuration

\subsubsection{Command syntax}

\begin{verbatim} frbtcfgbuf<TYPE><NUM> slot<SLOT> <CHN> cyc<CYC> <RXTX> max<MAX> <REP> ppi<PPI> int<INT>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}TYPE\mbox{$>$}} is 'S' for static segment buffers and 'D' for dynamic segment buffers,
\item \texttt{\mbox{$<$}NUM\mbox{$>$}} is the number of the buffer. Both static and dynamic buffers are numbered independently starting from zero,
\item \texttt{\mbox{$<$}SLOT\mbox{$>$}} is the number of the slot,
\item \texttt{\mbox{$<$}CHN\mbox{$>$}} is one of 'A', 'B' or 'AB' and identifies the used channel,
\item \texttt{\mbox{$<$}CYC\mbox{$>$}} is the cycle set when to send the buffer,
\item \texttt{\mbox{$<$}RXTX\mbox{$>$}} is either string \"{}rx\"{} or \"{}tx\"{},
\item \texttt{\mbox{$<$}MAX\mbox{$>$}} is the number determining the maximum payload (in hald-words),
\item \texttt{\mbox{$<$}REP\mbox{$>$}} is a string \"{}s\"{} or \"{}single\"{} for single transmission or \"{}c\"{} or \"{}continuous\"{} for continuous transmission,
\item \texttt{\mbox{$<$}PPI\mbox{$>$}} is 0 or 1 determining whether the payload preamble indicator is set,
\item \texttt{\mbox{$<$}INT\mbox{$>$}} is 0 or 1 and is currently ignored.
\end{itemize}

\subsubsection{Description}


The command sets the configuration parameters for static or dynamic buffers in user configuration. The parameters set by this command are applied by the frbtinitU command. Once frbtinit is called, it is no longer possible to change the parameters.

\subsubsection{Example}

\begin{verbatim} --> frbtcfgbufS0 slot2 AB cyc0 tx max9 continous ppi0 int1
frbtcfgbufS0 slot2 AB cyc0 tx max9  continous ppi0 int1
--> frbtcfgbufS1 slot1 AB cyc0 rx max9 continuous ppi0 int1
frbtcfgbufS1 slot1 AB cyc0 rx max9 continuous ppi0 int1
--> frbtcfgbufD0  slot9  A cyc0 rx max0x40 single ppi0 int0
frbtcfgbufD0 slot9  A cyc0 rx max64 single ppi0 int0
--> frbtcfgbufD1  slot10 A cyc0 tx max0x40 single ppi0 int0
frbtcfgbufD1 slot10  A cyc0 tx max64 single ppi0 int0\end{verbatim}

\subsection{frbtcfgfifo*}


Configure a RX FIFO message buffer in the user configuration

\subsubsection{Command syntax}

\begin{verbatim} frbtcfgfifo rejslot<SLOT> slotmask<MASK> depth<DEPTH> <CHN> cyc<CYC> max<MAX> <REJNULL> <REJSTAT>\end{verbatim}

where - \texttt{\mbox{$<$}SLOT\mbox{$>$}} is the number of the slot that will be rejected. If it is 0, no slot will be rejected, - \texttt{\mbox{$<$}MASK\mbox{$>$}} is a number specifying which bits of the \texttt{\mbox{$<$}SLOT\mbox{$>$}} will be ignored,- \texttt{\mbox{$<$}DEPTH\mbox{$>$}} is a number specifying the depth of the FIFO, - \texttt{\mbox{$<$}CHN\mbox{$>$}} is one of 'A', 'B' or 'AB' and identifies the used channel, - \texttt{\mbox{$<$}CYC\mbox{$>$}} is the cycle set when to send the buffer, - \texttt{\mbox{$<$}MAX\mbox{$>$}} is the number determining the maximum payload (in hald-words), - \texttt{\mbox{$<$}REJNULL\mbox{$>$}} is a string \"{}rejnull\"{} for rejecting NULL frames or \"{}accnull\"{} for accepting NULL frames, - \texttt{\mbox{$<$}REJSTAT\mbox{$>$}} is a string \"{}rejstat\"{} for rejecting frames in static segment or \"{}accstat\"{} for accepting frames from static segment,

\subsubsection{Description}


The command sets the configuration parameters for RX FIFO buffer in user configuration. The parameters set by this command are applied by the frbtinitU command. Once frbtinit is called, it is no longer possible to change the parameters. Those messages, which are not accepted by any other buffer and pass the FIFO rejection filter will be stored in the RX FIFO buffer.

\subsubsection{Example}

\begin{verbatim} --> frbtcfgfifo rejslot6 slotmask6 depth5 AB cyc0 max0x20 rejnull accstat
frbtcfgfifo rejslot6 slotmask6 depth5 AB cyc0 max0x20 rejnull accstat\end{verbatim}

\subsection{frbtchecktx*}


Print the status of the transmit buffer

\subsubsection{Command syntax}

\begin{verbatim} frbtchecktx<FRID>\end{verbatim}

where \texttt{\mbox{$<$}FRID\mbox{$>$}} is a decimal number specifying the ID of the frame for which a buffer has been configured.

\subsubsection{Description}


The command stands for Fr\_CheckTxLPduStatus function from the Autosar specification. The command finds the first buffer assigned to the specified frame ID, reads its status and prints it. The buffer can be in one of the two states:
\begin{itemize}
\item Message transmission is pending, which means that the buffer has not yet sent its message in single shot mode or that it is in continuous mode.
\item No message transmission is pending, which means that the buffer is in single shot mode and the message has already been sent.
\end{itemize}

\subsubsection{Example}

\begin{verbatim} --> frbtchecktx1
Message transmission is not pending.\end{verbatim}

\subsection{frbtchstat}


Print channel A and B status

\subsubsection{Command syntax}

\begin{verbatim} frbtchstat\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_GetChannelStatus function from the Autosar specification.

\subsubsection{Example}

\begin{verbatim} --> frbtchstat
Channel A status:
    aggregated channel status vSS!ValidFrame: TRUE
    aggregated channel status vSS!SyntaxError: FALSE
    aggregated channel status vSS!ContentError: FALSE
    aggregated channel status additional communication: FALSE
    aggregated channel status vSS!Bviolation: FALSE
    aggregated channel status vSS!TxConflict: FALSE
    Not used (0): FALSE
    Not used (0): FALSE
    symbol window status data vSS!ValidMTS: FALSE
    symbol window status data vSS!SyntaxError: FALSE
    symbol window status data vSS!Bviolation: FALSE
    symbol window status data vSS!TxConflict: FALSE
    NIT status data vSS!SyntaxError: FALSE
    NIT status data vSS!Bviolation: FALSE
    Not used (0): FALSE
    Not used (0): FALSE
Channel B status:
    aggregated channel status vSS!ValidFrame: TRUE
    aggregated channel status vSS!SyntaxError: FALSE
    aggregated channel status vSS!ContentError: FALSE
    aggregated channel status additional communication: FALSE
    aggregated channel status vSS!Bviolation: FALSE
    aggregated channel status vSS!TxConflict: FALSE
    Not used (0): FALSE
    Not used (0): FALSE
    symbol window status data vSS!ValidMTS: FALSE
    symbol window status data vSS!SyntaxError: FALSE
    symbol window status data vSS!Bviolation: FALSE
    symbol window status data vSS!TxConflict: FALSE
    NIT status data vSS!SyntaxError: FALSE
    NIT status data vSS!Bviolation: FALSE
    Not used (0): FALSE
    Not used (0): FALSE\end{verbatim}

\subsection{frbtclkcor}


Print clock correction (rate and offset)

\subsubsection{Command syntax}

\begin{verbatim} frbtclkcor\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_GetClockCorrection function from the Autosar specification.

\subsubsection{Example}

\begin{verbatim} --> frbtclkcor
Rate correction: 0
Offset correction: 0\end{verbatim}

\subsection{frbtconfig*}


Set the user configuration parameters

\subsubsection{Command syntax}

\begin{verbatim} frbtconfig<TYPE> <PARAMS>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}TYPE\mbox{$>$}} is a string specifying the type of parameters to be set. It can be: \"{}cluster\"{} or \"{}node\"{}
\item \texttt{\mbox{$<$}PARAMS\mbox{$>$}} is a sequence of numbers separated by spaces. Each number stands for one parameter.
\end{itemize}

\subsubsection{Description}


The command takes the configuration parameters in the form of a string and sets the appropriate type of the FlexRay parameters. It is necessary to configure parameters of at least cluster, and node and one static buffer (see frbtcfgbuf command). The parameters set by this command are applied by the frbtinitU command. Once frbtinit is called, it is no longer possible to change the parameters.

The type of the parameters can be selected by the \texttt{\mbox{$<$}TYPE\mbox{$>$}} selector.

Type \"{}cluster\"{} sets global FlexRay network parameters. It expects a sequence of 25 parameters in this order:
\begin{itemize}
\item 1) gColdStartAttempts
\item 2) gListenNoise
\item 3) gMacroPerCycle
\item 4) gMaxWithoutClockCorrectionFatal
\item 5) gMaxWithoutClockCorrectionPassive
\item 6) gNetworkManagementVectorLength
\item 7) gNumberOfMinislots
\item 8) gNumberOfStaticSlots
\item 9) gOffsetCorrectionStart
\item 10) gPayloadLengthStatic
\item 11) gSyncNodeMax
\item 12) gdActionPointOffset
\item 13) gdCASRxLowMax
\item 14) gdDynamicSlotIdlePhase
\item 15) gdMinislot
\item 16) gdMinislotActionPointOffset
\item 17) gdNIT
\item 18) gdSampleClockPeriod
\item 19) gdStaticSlot
\item 20) gdTSSTransmitter
\item 21) gdWakeupSymbolRxIdle
\item 22) gdWakeupSymbolRxLow
\item 23) gdWakeupSymbolRxWindow
\item 24) gdWakeupSymbolTxIdle
\item 25) gdWakeupSymbolTxLow
\end{itemize}

Type \"{}node\"{} sets local FlexRay network parameters. It expects a sequence of 28 parameters in this order:
\begin{itemize}
\item 1) pAllowHaltDueToClock
\item 2) pAllowPassiveToActive
\item 3) pChannels (0 - A, 1 - B, 2 - AB)
\item 4) pClusterDriftDamping
\item 5) pDelayCompensationA
\item 6) pDelayCompensationB
\item 7) pExternOffsetCorrection
\item 8) pExternRateCorrection
\item 9) pKeySlotUsedForStartup
\item 10) pKeySlotUsedForSync
\item 11) pLatestTx
\item 12) pMacroInitialOffsetA
\item 13) pMacroInitialOffsetB
\item 14) pMicroInitialOffsetA
\item 15) pMicroInitialOffsetB
\item 16) pMicroPerCycle
\item 17) pRateCorrectionOut
\item 18) pOffsetCorrectionOut
\item 19) pSamplesPerMicrotick
\item 20) pSingleSlotEnabled
\item 21) pWakeupChannel (0 - A, 1 - B)
\item 22) pWakeupPattern
\item 23) pdAcceptedStartupRange
\item 24) pdListenTimeout
\item 25) pdMaxDrift
\item 26) pDecodingCorrection
\item 27) syncFramePayloadMultiplexEnabled
\item 28) secureBuffers (0 - FR\emph{SB}RECONFIG\emph{ENABLED, 1 - FR}SB\emph{STAT}REC\emph{DISABLED}STAT\emph{TR}DISABLED, 2 - FR\emph{SB}ALL\emph{REC}DISABLED, 3 - FR\emph{SB}ALL\emph{REC}DISABLED\emph{STAT}TR\_DISABLED)
\end{itemize}

\subsubsection{Example}

\begin{verbatim} --> frbtconfigcluster 0x2 0xF 0x15E0 0xF 0xF 0xC 0x15A 0x8 0xAE4 0x9 0xF 0x4 0x43 0x1 0x4 0x2 0xAE3 0x0 0x56 0xA 0x12 0x12 0x4C 0xB4 0x3C
FlexRay cluster configuration accepted.
--> frbtconfignode 0x0 0x0 0x2 0x1 0x3 0x3 0x0 0x0 0x1 0x1 0x10D 0x6 0x6 0x18 0x18 0x36B00 0xCD 0x151 0x0 0x1 0x0 0x2 0x81 0x36DA2 0x151 0x33 0x0 0x0
FlexRay node configuration accepted.\end{verbatim}

\subsection{frbtdisable*}


Disable the buffers assigned to the frame

\subsubsection{Command syntax}

\begin{verbatim} frbtdisable<FRID>\end{verbatim}

where \texttt{\mbox{$<$}FRID\mbox{$>$}} is a decimal number specifying the ID of a frame. The buffers configure for this frame will be disabled.

\subsubsection{Description}


The command stands for Fr\_DisableLPdu function from the Autosar specification. The command finds all buffers assigned to the specified frame ID and disables them. This means that those buffers will be unavailable for the communication until their reconfiguration (which is not yet implemented). Buffers used for startup frames and FIFO RX buffers cannot be disabled.

\subsubsection{Example}

\begin{verbatim} --> frbtdisable3
Buffer disabled.\end{verbatim}

\subsection{frbtgetpocst}


Print FlexRay POC status

\subsubsection{Command syntax}

\begin{verbatim} frbtgetpocst\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_GetPOCStatus function from the Autosar specification. It prints the main FlexRay POC status values in the form of a table. The command should be called after the frbtinit command.

\subsubsection{Example}

\begin{verbatim} --> frbtgetpocst
POC status:
CHIHaltRequest: FALSE
CHIReadyRequest: FALSE
ColdstartNoise: FALSE
Freeze: FALSE
ErrorMode: ACTIVE
SlotMode: ALL
StartupState: UNDEFINED
State: READY
WakeupStatus: UNDEFINED\end{verbatim}

\subsection{frbtgetsyncfrlist*}


Print the list of sync frames transmitted on both channels via the odd and even communication cycle

\subsubsection{Command syntax}

\begin{verbatim} frbtgetsyncfrlist<LENGTH>\end{verbatim}

where \texttt{\mbox{$<$}LENGTH\mbox{$>$}} is a decimal number in range 0 - 15, specifying the length of the list to be printed.

\subsubsection{Description}


The command stands for Fr\_GetSyncFrameList function from the Autosar specification.

\subsubsection{Example}

\begin{verbatim} --> frbtgetsyncfrlist2
| Channel A even | channel B even | channel A odd  | channel B odd  |
|----------------|----------------|----------------|----------------|
| 1              | 1              | 1              | 1              |
| 2              | 2              | 2              | 2              |
|----------------|----------------|----------------|----------------|\end{verbatim}

\subsection{frbtgetwurxstat}


Prints whether the wake up pattern has been or has not been received

\subsubsection{Command syntax}

\begin{verbatim} frbtgetwurxstat\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_GetWakeupRxStatus function from the Autosar specification. The status of the wake up receiving is bitcoded in the controller. This command decodes and prints it in a readable format.

\subsubsection{Example}

\begin{verbatim} --> frbtgetwurxstat
Wake up pattern was not yet received on channel A.
Wake up pattern was not yet received on channel B.\end{verbatim}

\subsection{frbtglobtime}


Print actual global time of the network

\subsubsection{Command syntax}

\begin{verbatim} frbtglobtime\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_GetGlobalTime function from the Autosar specification. The command prints the time as a number of the current cycle and the offset in the cycle in macroticks.

\subsubsection{Example}

\begin{verbatim} --> frbtglobtime
Cycle number: 23
Macrotick number: 6\end{verbatim}

\subsection{frbthalt}


Halt FlexRay communication after the end of the actual communication cycle

\subsubsection{Command syntax}

\begin{verbatim} frbthalt\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_HaltCommunication function from the Autosar specification. The command invokes the FlexRay POC command HALT, which means that communication is stopped after the end of the actual communication cycle. On the opposite side, there is a frbtfreeze command, which stops the communication immediately. To restart the communication, the frbtinit and frbtstart commands have to be called.

\subsubsection{Example}

\begin{verbatim} --> frbthalt
FlexRay node communication halted.\end{verbatim}

\subsection{frbtinit?}


Initialize a FlexRay node

\subsubsection{Command syntax}

\begin{verbatim} frbtinit<CFG>\end{verbatim}

where \texttt{\mbox{$<$}CFG\mbox{$>$}} identifies the configuration to use. It can be one of A, B or U. The A and B are predefined configurations. If U is specified, the user configuration previously set by frbtconfig command is used.

\subsubsection{Description}


The command stands for Fr\emph{Init and Fr}ControllerInit functions from the Autosar specification. It initializes the internal data structures of the driver and then, based on those data, the controller configuration is done. During the controller configuration the parameters of the cluster, node, message RAM and buffers are checked. If anything goes bad, the command returns an error number, which can be decoded by macros defined in driver header file fr\emph{tms570.h with prefix ERR}PARAM. If all parameters are OK, all necessary registers of the controller are initialized according to the specified configuration parameters. At the end of the command, the FlexRay controller is switched into READY state and all buffers are configured to send NULL frames. This command should be called as the very first command, when trying to communicate over the FlexRay bus.

\subsubsection{Example}

\begin{verbatim} --> frbtinitA
FlexRay driver initialized.
FlexRay controller initialized.\end{verbatim}

\subsection{frbtnmvector}


Print network management vector of the node

\subsubsection{Command syntax}

\begin{verbatim} frbtnmvector\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_GetNmVector function from the Autosar specification. It prints the values of the network management vector as hexadecimal numbers.

\subsubsection{Example}

\begin{verbatim} --> frbtnmvector
Network management vector: 0 0 0 0 0 0 0 0 0 0 0 0\end{verbatim}

\subsection{frbtnmwatch}


Watch the changes of the network managment vector in real-time

\subsubsection{Command syntax}

\begin{verbatim} frbtnmwatch\end{verbatim}

\subsubsection{Description}


Reads the network management vector every 100 ms and prints it out.

\subsubsection{Example}

\begin{verbatim} --> frbtnmwatch
Network management vector: 0 0 0 0 0 0 0 0 0 0 0 0\end{verbatim}

\subsection{frbtreceive*}


Receive a new message

\subsubsection{Command syntax}

\begin{verbatim} frbtreceive<FRID>\end{verbatim}

where \texttt{\mbox{$<$}FRID\mbox{$>$}} is a decimal number specifying the ID of the frame for which a buffer was configured.

\subsubsection{Description}


The command stands for Fr\_ReceiveRxLPdu function from the Autosar specification. The command finds the first buffer assigned to the specified frame ID, determines if a new message has been received and reads it out of the buffer. If no message was received, \"{}No message received\"{} is printed. If a new message was received, all message data are printed as a hexadecimal values. If a new message was retrieved from a FIFO buffer and more messages are available in it, \"{}More messages are still in FIFO\"{} is printed.

\subsubsection{Example}

\begin{verbatim} --> frbtreceive0
More messages are still in FIFO:
Received message (32 B):
 ee ff 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00\end{verbatim}

\subsection{frbtreconfigurebuf*}


Reconfigure a buffer to communicate in another slot

\subsubsection{Command syntax}

\begin{verbatim} frbtreconfigurebuf id<ID> slot<SLOT> <CHN> cycset<CYCS> cycoffset<CYCO> max<MAX>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}ID\mbox{$>$}} is a number specifying a slot, where the buffer is currently communicating,
\item \texttt{\mbox{$<$}SLOT\mbox{$>$}} is a number, where buffer will be communicating after the reconfiguration,
\item \texttt{\mbox{$<$}CHN\mbox{$>$}} is one of 'A', 'B' or 'AB' and identifies the used channel,
\item \texttt{\mbox{$<$}CYCS\mbox{$>$}} is the cycle set. It has to be one of 0, 1, 2, 4, 8, 16, 32, 64. It specifies together with \texttt{\mbox{$<$}CYCO\mbox{$>$}} the cycle filtering.
\item \texttt{\mbox{$<$}CYCO\mbox{$>$}} is the cycle offset. It has to be in range 0 - \texttt{\mbox{$<$}CYCS\mbox{$>$}}-1- \texttt{\mbox{$<$}MAX\mbox{$>$}} is the number determining the maximum payload (in hald-words).
\end{itemize}

\subsubsection{Description}


The command stands for Fr\_ReconfigLPDu function from the Autosar specification. It reconfigures specified buffer to communicate in different slot. The reconfiguration must be allowed in node configuration parameter secureBuffers. Buffers used for synchronization or assigned to the FIFO are not reconfigurable. The command can be called any time when the communication is running.

\subsubsection{Example}

\begin{verbatim} --> frbtreconfigurebuf id2 slot3 AB cycset1 cycoffset0 max9
frbtreconfigurebuf id2 slot3 AB cycset1 cycoffset0 max9\end{verbatim}

\subsection{frbtsettimer*}


Set and start timer

\subsubsection{Command syntax}

\begin{verbatim} frbtsettimer<TMID> <CYCLE> <OFFSET>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}TMID\mbox{$>$}} is a number (0, 1) specifying the timer.
\item \texttt{\mbox{$<$}CYCLE\mbox{$>$}} is a 7-bit number (0 - 127) specifying the set of cycles, in which timer interrupt should be requested. The first set bit determines the period (1, 2, ..., 64) and the lower bits determine the offset in cycles within the period.
\item \texttt{\mbox{$<$}OFFSET\mbox{$>$}} is a decimal number (0 - 16383) specifying the offset in macroticks, where precisely in the cycle should be the timer interrupt requested.
\end{itemize}

\subsubsection{Description}


The command is similar to Fr\_SetAbsoluteTimer function from the Autosar specification. The difference is that the command allows to specify a set of cycles, not only one of 64 cycles. It sets the timer selected by the parameter and enables it.

Before using this command, FlexRay communication has to be started (see frbtstart).

\subsubsection{Example}

\begin{verbatim} --> frbtsettimer0 32 50
Timer was set for every 32-th cycle, offset 0, macrotick 50
--> frbtsettimer0 31 50
Timer was set for every 16-th cycle, offset 15, macrotick 50
--> frbtsettimer0 0x42 0
Timer was set for every 64-th cycle, offset 2, macrotick 0\end{verbatim}

\subsection{frbtsetwuch?}


Set wake up channel

\subsubsection{Command syntax}

\begin{verbatim} frbtsetwuch<CHANNEL>\end{verbatim}

where \texttt{\mbox{$<$}CHANNEL\mbox{$>$}} is a character A or B, specifying the channel.

\subsubsection{Description}


The command stands for Fr\_SetWakeupChannel function from the Autosar specification. Wake up channel is the channel, where Wake Up Pattern is sent. The channel can be set after the driver and controller are initialized and before the communication is running. The actual wake-up pattern is sent by the frbtwup command.

\subsubsection{Example}

\begin{verbatim} --> frbtsetwuchA
Wake up channel has been set.\end{verbatim}

\subsection{frbtstart}


Start a new FlexRay network or join to the existing one

\subsubsection{Command syntax}

\begin{verbatim} frbtstart\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_StartCommunication function from the Autosar specification. If the FlexRay node is configured as a coldstarter node (as for example by frbtinitA/B command), then the command first listen on the bus. When it does not detect any existing bus communication, it tries to initiate a new network. If the initiation fails, the FlexRay controller is switched back to the ready state for another attempt (calling frbtstart again). If the FlexRay node is configured as non-coldstarter, it is listening on the bus until some existing communication is detected.

The command should be called after the frbtinit command.

\subsubsection{Example}

\begin{verbatim} --> frbtstart
FlexRay communication is running.\end{verbatim}

\subsection{frbttimerirq*}


Perform selected action on the timer IRQ

\subsubsection{Command syntax}

\begin{verbatim} frbttimerirq<TMID> <ACTION> - Run the <ACTION> on specified timer
frbttimerirq<TMID> - Get timer IRQ status\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}TMID\mbox{$>$}} is a number (0, 1) specifying the timer.
\item where \texttt{\mbox{$<$}ACTION\mbox{$>$}} is a string specifying the action to be performed on the selected timer IRQ.
\end{itemize}

\texttt{\mbox{$<$}ACTIONS\mbox{$>$}} can be one of:
\begin{itemize}
\item EN - Enable the IRQ on the selected timer
\item DIS - Disable the IRQ on the selected timer
\item ACK - Acknowledge the IRQ on the selected timer (reset flag in the register).
\end{itemize}

\subsubsection{Description}


The command stands for Fr\emph{EnableAbsoluteTimerIRQ, Fr}AckAbsoluteTimerIRQ, Fr\emph{DisableAbsoluteTimerIRQ and Fr}GetAbsoluteTimerIRQStatus functions from the Autosar specification. It masks or demasks the IRQ for the timer, or acknowledges the interrupt request. If no action is specified it prints whether the IRQ is pending for the timer.

\subsubsection{Example}

\begin{verbatim} --> frbttimerirq0
IRQ = FALSE

--> frbttimerirq0 EN
OK\end{verbatim}

\subsection{frbttransmit*}


Transmit data in selected frame

\subsubsection{Command syntax}

\begin{verbatim} frbttransmit<FRID> <DATA>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}FRID\mbox{$>$}} is a decimal number specifying the ID of the frame for which a buffer has been configured.
\item \texttt{\mbox{$<$}DATA\mbox{$>$}} is a sequence of hexadecimal numbers separated by spaces. Each number represents one byte of the message.
\end{itemize}

\subsubsection{Description}


The command stands for Fr\_TransmitTxLPdu function from the Autosar specification. The command finds the first buffer assigned to the specified frame ID and copies the given data into its data section in the message RAM. Transmit request is set after the data are copied, so transmission starts at the next occurrence of the frame in the communication cycle.

\subsubsection{Example}

\begin{verbatim} --> frbttransmit1 12 34 56 AA BB CC
Data were set for transmission.\end{verbatim}

\subsection{frbtversion}


Print FlexRay driver version information

\subsubsection{Command syntax}

\begin{verbatim} frbtversion\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_GetVersionInfo function from the Autosar specification. It reads and prints the information about vendor, module and version of the FlexRay driver

\subsubsection{Example}

\begin{verbatim} --> frbtversion
vendorID: 0xAAAA
moduleID: 0xBBBB
sw_major_version: 0x1
sw_minor_version: 0x2
sw_patch_version: 0x4\end{verbatim}

\subsection{frbtwup}


Initiate the wake up procedure

\subsubsection{Command syntax}

\begin{verbatim} frbtwup\end{verbatim}

\subsubsection{Description}


The command stands for Fr\_SendWUP function from the Autosar specification. It initiates the wake up procedure by switching FlexRay controller state machine to WAKEUP state.

\subsubsection{Example}

\begin{verbatim} --> frbtwup
Wake up pattern has been sent.\end{verbatim}

\subsection{hbrcontrol*}


Set the motor voltage direction and size in percent

\subsubsection{Command syntax}

\begin{verbatim} hbrcontrol<SPEED>\end{verbatim}

where \texttt{\mbox{$<$}SPEED\mbox{$>$}} specifies direction and PWM duty cycle in percent (a number in range -100, 100).

\subsubsection{Description}


The command sets the direction and the size of the voltage at the HBR output.

HBR has to be enabled by the \texttt{hbrenable} command before calling this command.

\subsubsection{Examples}

\begin{verbatim} --> hbrcontrol-25
hbrcontrol =-25\end{verbatim}

Rotates the motor to the left with 25\% duty cycle.
\begin{verbatim} --> hbrcontrol25
hbrcontrol =25\end{verbatim}

Rotates the motor to the right with 25\% duty cycle.
\begin{verbatim} --> hbrcontrol0
hbrcontrol =0\end{verbatim}

Stops the motor, but the H-Bridge output is active (low-side active free wheeling).

\subsection{hbrdisable}


Disable the H-bridge

\subsubsection{Command syntax}

\begin{verbatim} hbrdisable\end{verbatim}

\subsubsection{Description}


The command disables the H-bridge HBR, which means that the PWM is stopped and the enable signal is cleared. The watchdog task is left running, because it is harmless.

After the H-bridge is disabled, it cannot be controlled by any command until it is enabled again by the \texttt{hbrenable} command.

\subsubsection{Example}

\begin{verbatim} --> hbrdisable
hbrdisable=0\end{verbatim}

Stops motor and disables the H-bridge.

\subsection{hbrenable*}


Enable the H-bridge and set its PWM period

\subsubsection{Command syntax}

\begin{verbatim} hbrenable<PER>\end{verbatim}

where \texttt{\mbox{$<$}PER\mbox{$>$}} is PWM period in microseconds.

\subsubsection{Description}


This command enables the H-bridge (HBR pin), i.e. the enable signal the H-bridge chip is set, the watchdog reset task is started and the PWM is configured with the specified period and duty cycle 0\%.

If the period is zero, the default frequency of 18kHz is used instead. Minimum period is 50. This command should be called before any other command starting with hbr is used. If H-bridge is already enabled, an error is printed.

\subsubsection{Example}

\begin{verbatim} --> hbrenable1000
hbrenable =1000\end{verbatim}

Enables HBR with period 1000 microseconds (frequency 1 kHz). HBR output is still inactive, but ready for other commands.

\subsection{help}


Print help for commands

\subsubsection{Syntax}


help \mbox{$[$}command\mbox{$]$}

\subsubsection{Description}


This command without parameter prints the list of all available commands with short help text for each of them. If a parameter is provided, the command prints a long description for given command.

\subsection{houtfail*}


Test if some HOUT pin is in the fault state

\subsubsection{Command syntax}

\begin{verbatim} houtfail<PIN>\end{verbatim}

where \texttt{\mbox{$<$}PIN\mbox{$>$}} is in range 1-6

\subsubsection{Description}


This command tests, if HOUT pin is in a good condition. When the circuit controlling HOUT pin detects some failure, it signals that on HOUT\_DIAG output. This command is supposed to read this output and print its state.

Possible outputs of this command:
\begin{itemize}
\item OK - no failure detected
\item FAIL - a failure detected
\item NOT RUNNING - PWM was set set up and started
\end{itemize}

Note: Before using this command, houtpwmstart and houtpwm commands should be called.

\subsubsection{Example}

\begin{verbatim} --> houtpwm6 1000 25
--> houtpwmstart6
--> houtfail6
OK\end{verbatim}

Detects the state of the HOUT1 and prints OK, FAIL or NOT RUNNING.

\subsection{houtifbk}


Read values from HOUT current feedback

\subsubsection{Command syntax}

\begin{verbatim} houtifbk\end{verbatim}

\subsubsection{Description}


The command reads analog values from HOUT\_IFBK pins and prints them in a table.

\subsubsection{Example}


--\mbox{$>$} houtifbk HOUT1: 0 HOUT2: 134223784 HOUT3: 134223784 HOUT4: 0 HOUT5: 38924 HOUT6: 1342231444

\subsection{houtpwm*}


Set or get actual PWM parameters

\subsubsection{Command syntax}

\begin{verbatim} houtpwm<PIN> <PER> <DUTY>
houtpwm<PIN>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1-6
\item \texttt{\mbox{$<$}PER\mbox{$>$}} is a length of the PWM period in microseconds
\item \texttt{\mbox{$<$}DUTY\mbox{$>$}} is a the PWM duty cycle in percent (0-100)
\end{itemize}

\subsubsection{Description}


This command can be used to set or get HOUT PWM parameters.

\subsubsection{Example}

\begin{verbatim} --> houtpwm1 1000 25\end{verbatim}

HOUT1 PWM will have the period of 1ms and will be active for 25\% of this period.
\begin{verbatim} --> houtpwm1
houtpwm1_period=1000
houtpwm1_duty=25\end{verbatim}

Prints the actual period of HOUT1 PWM in microseconds and the duty cycle in percents.

\subsection{houtstartpwm*}


Start generating PWM signal on HOUT

\subsubsection{Command syntax}

\begin{verbatim} houtstartpwm<PIN>\end{verbatim}

where \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1-6

\subsubsection{Description}


This command starts to generate the PWM signal on the specified HOUT pin. The HOUT PWM has to be previously set by the houtpwm command, otherwise an error is printed.

\subsubsection{Example}

\begin{verbatim} --> houtpwm1 1000 25
--> houtstartpwm1\end{verbatim}

HOUT1 PWM generation will be started.

\subsection{houtstoppwm*}


Stop generating of PWM signal on HOUT

\subsubsection{Command syntax}

\begin{verbatim} houtstoppwm<PIN>\end{verbatim}

where \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1-6

\subsubsection{Description}


This command stops generating the PWM signal on the selected pin.

\subsubsection{Example}

\begin{verbatim} --> houtstoppwm1\end{verbatim}

HOUT1 PWM generation will be deactivated.

\subsection{lintest}


Test the digital loopback on LIN

\subsubsection{Command syntax}

\begin{verbatim} lintest\end{verbatim}

\subsubsection{Description}


This command can be used for testing the LIN. The command starts to send a short message on the LIN port and is testing if it is correctly received via an internal loopback.

\subsection{loutdiag*}


Read a diagnostic value from an LOUT pin

\subsubsection{Command syntax}

\begin{verbatim} loutdiag<PIN>\end{verbatim}

where \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1-8

\subsubsection{Description}


The command reads a logical value of the LOUT diagnostic signal.

\subsubsection{Example}

\begin{verbatim} --> loutdiag1\end{verbatim}

Reads value of the LOUT1 diagnostic signal.

\subsection{loutset*}


Set a value of the LOUT pin

\subsubsection{Command syntax}

\begin{verbatim} loutset<PIN> <VALUE>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}PIN\mbox{$>$}} is a number in range 1-8
\item \texttt{\mbox{$<$}VALUE\mbox{$>$}} is a binary value to be set (0 or 1)
\end{itemize}

\subsubsection{Description}


The command sets the digital value on the LOUT pin.

\subsubsection{Example}

\begin{verbatim} --> loutset1 1\end{verbatim}

Sets LOUT1 to 1.
\begin{verbatim} --> loutset2 0\end{verbatim}

Sets LOUT2 to 0.

\subsection{pindir*}


Set the pin direction

\subsubsection{Command syntax}

\begin{verbatim} pindir<NAME> <DIR>
pindir<NAME>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}NAME\mbox{$>$}} is a string identifying the pin
\item DIR is be either 0 (input) or 1 (output)
\end{itemize}

\subsubsection{Description}


This command is used to set or get direction of the particular pin.

The list of valid pin names can be obtained with pinlist command.

Most of the pins are accessible indirectly via other highlevel commands HBR\_EN is, for example, controlled by the hbrenable command. This command serves as supplement to highlevel commands for testing purpose.

\subsubsection{Example}

\begin{verbatim} --> pindirHBREN 1
pindirHBREN=1\end{verbatim}

Sets the HBR\_EN pin as output.
\begin{verbatim} --> pindirHBREN
pindirHBREN=1\end{verbatim}

Gets the direction of the HBR\_EN pin.

\subsection{pinlist}


Print a list of all defined pins.

\subsubsection{Command syntax}

\begin{verbatim} pinlist\end{verbatim}

\subsubsection{Description}


The command prints a list of all defined pins accessible by pinval and pindir commands.

\subsubsection{Example}

\begin{verbatim} --> pinlist
List of all defined pins. Those names can be used by pinval command.
FANCTRL
ETHRST
VBAT1EN
VBAT2EN
VBAT3EN
VBATEN
SPICSA
SPICSB
MOUT1EN
MOUT2EN
CANNSTB
CANEN
LIN2NSLP
LIN1NSLP
DININT
DIN8
DIN9
DIN10
DIN11
DIN12
DIN13
DIN14
DIN15
MOUT6EN
MOUT5EN
MOUT6IN
MOUT5IN
MOUT4EN
MOUT3EN
MOUT4IN
MOUT3IN
HBREN
HBRDIR
HBRPWM
MOUT1IN
MOUT2IN
HOUT1IN
HOUT1DIAG
HOUT2IN
HOUT2DIAG
HOUT3IN
HOUT3DIAG
HOUT4IN
HOUT4DIAG
HOUT5IN
HOUT5DIAG
HOUT6IN
HOUT6DIAG\end{verbatim}

\subsection{pinval*}


Set or get the pin value

\subsubsection{Command syntax}

\begin{verbatim} pinval<NAME> <VAL>
pinval<NAME>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}NAME\mbox{$>$}} is a string identifying the pin
\item \texttt{\mbox{$<$}VAL\mbox{$>$}} can be 0 or 1
\end{itemize}

\subsubsection{Description}


This command is sets or gets a value of the particular pin.

The list of valid pin names can be obtained with pinlist command.

Most of the pins are accessible indirectly via other highlevel commands. HBR\_EN is, for example, controlled by the hbrenable command. This command serves as supplement to highlevel commands for testing purpose.

\subsubsection{Example}

\begin{verbatim} --> pinvalHBREN 1
pinvalHBREN=1\end{verbatim}

Sets the HBR\_EN pin to 1.
\begin{verbatim} --> pinvalHBREN
pinvalHBREN=1\end{verbatim}

Gets a value of the HBR\_EN pin.

\subsection{portlist}


Print a list of all port names

\subsubsection{Command syntax}

\begin{verbatim}  portlist\end{verbatim}

\subsubsection{Description}


This command prints the list of all defined ports accessible via the portval command. Each record of the list is a couple of PortName-PortInterface, where PortInterface is SPI, ADC or GPIO. The type of the MCU\mbox{$<$}-\mbox{$>$}port interface slightly modifies the meaning of the portval command.

\subsubsection{Example}

\begin{verbatim}  --> portlist
 List of all defined ports with its type. Those names can be used by portval command.
 DINMCU, GPIO
 DINSPI, SPI
 HOUTDIAG, GPIO
 HOUTIN, GPIO
 HOUTIFBK, ADC
 ADC, ADC
 LOUT, SPI
 DAC12, SPI
 DAC34, SPI
 DACDREF, SPI
 HBR, SPI
 FRAY1, SPI
 FRAY2, SPI
 MOUTEN, GPIO
 MOUTIN, GPIO\end{verbatim}

\subsection{portval*}


Read or write values from or to the port

\subsubsection{Command syntax}

\begin{verbatim}  portval<NAME> <VAL>
 portval<NAME>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}NAME\mbox{$>$}} is a string specifying the name of the port
\item \texttt{\mbox{$<$}VAL\mbox{$>$}} is a sequence of hexadecimal numbers, separated by spaces, e.g. 12 AA CD
\end{itemize}

\subsubsection{Description}


This command sets or gets values of all pins on the specified port. If the port is connected to the GPIO interface of the MCU, then when writing the value, the lowest significant bit of the argument is assigned to the first pin, the second bit is assigned to the second pin, etc. The command returns zero. When reading from the port, the command returns values for each pin.

If the port is connected to the SPI interface of the MCU, then it is write only and the argument is interpreted as a command for the port controller. The command returns the response from the port controller. For command examples please refer to the project wiki

If the port is connected to the ADC interface of the MCU, then it is read only and returns values for each ADC pin.

Port names and interface type can be obtained with the portlist command.

NOTE: For successful communication with the HBR, HBR\_EN pin must be set first.

\subsubsection{Example}

\begin{verbatim}  --> portvalMOUTIN 3A
 portvalMOUTIN=0
 --> portvalMOUTIN
 0
 1
 0
 1
 1
 1\end{verbatim}

This pair of commands sets: MOUT1INMOUT1IN=0 MOUT2IN=1 MOUT3IN=0 MOUT4IN=1 MOUT5IN=1 MOUT6IN=1 Which is shown in getter output

\subsection{poweroff}


Disables VBATEN and VBAT1EN power supply

\subsubsection{Command syntax}

\begin{verbatim} poweroff\end{verbatim}

\subsubsection{Description}


This command turns off VBAT and VBAT1 voltages.

\subsection{poweron}


Enable VBATEN and VBAT1EN power supply by using PWM hack

\subsubsection{Command syntax}

\begin{verbatim} poweron\end{verbatim}

\subsubsection{Description}


This command tries to work around error on VBAT power supply wiring and attempts to switch the power supply on.

It turns on the VBAT voltage by slowly charging the capacitors connected to the VBAT1 signal by using the software-generated PWM signal with increasing duty cycle.

The poweron command has to be launched before any access to any SPI peripherals, otherwise they will not work (or the power supply has to be electrically bypassed).

Please note that parameters for the PWM signal may change from device to device and it might be necessary to tune them (in source code) for each device.

\subsection{sdramlogtest}


Open a command subprocessor for managing SDRAM logging

\subsubsection{Command syntax}

\begin{verbatim} sdramlogtest\end{verbatim}

\subsubsection{Description}


The command opens a subcommand processor, which contains testing commands for logging into SDRAM.

\subsection{sdramtest}


Test if the SDRAM module is connected and if so, measures its capacity

\subsubsection{Command syntax}

\begin{verbatim} sdramtest\end{verbatim}

\subsubsection{Description}


This command tests SDRAM address space by writing and reading a pattern to/from it. It detects the SDRAM capacity.

\subsubsection{Example}

\begin{verbatim} --> sdramtest
SDRAM installed: 64 MB\end{verbatim}

\subsection{sleep}


Sleep the board

\subsubsection{Syntax}


sleep

\subsubsection{Description}


This command configures the LIN and CAN peripherals to enter sleep mode and turn the whole device into sleep mode. External signal on CAN or LIN will wake the device up.

\subsection{spimst*}


Request SPI master communication

\subsubsection{Command syntax}

\begin{verbatim} spimst<SPI> <ADDR> <DATA>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}SPI\mbox{$>$}} is a number in range 0 - 4
\item \texttt{\mbox{$<$}ADDR\mbox{$>$}} is a number in range 0 - 2
\item \texttt{\mbox{$<$}DATA\mbox{$>$}} is a sequence of hexadecimal numbers, separated by spaces, e.g. 12 AA CD
\end{itemize}

\subsubsection{Description}


The command sends given data to the SPI peripheral and prints the response. The response contains the address and the received data in parentheses.

\subsubsection{Example}

\begin{verbatim} --> spimst1 0 7F 00 00
spirx:0x0(0x3f,0xc0,0xff)\end{verbatim}

Sends reset command (0x7F0000) to the DIN peripheral.

\subsection{spitr*}


Translate response from an SPI peripheral

\subsubsection{Command syntax}

\begin{verbatim} spitr<NAME> <CMD> <RESP>\end{verbatim}

where
\begin{itemize}
\item \texttt{\mbox{$<$}NAME\mbox{$>$}} is a string specifying the name of the peripheral (one of DINSPI, LOUT, DAC12, DAC34, HBR, FRAY1 and FRAY2)
\item \texttt{\mbox{$<$}CMD\mbox{$>$}} is a hexadecimal number in range 0 - FFFFFFFF
\item \texttt{\mbox{$<$}RESP\mbox{$>$}} is a hexadecimal number in range 0 - FFFFFFFF
\end{itemize}

\subsubsection{Description}


This command translates a response from SPI from many different peripherals into a human readable form. The SPI response is in the form of a hexadecimal number, which encodes the information. This commands takes this response, the command which produced this response, the name of the peripheral and translates the response into the attribute-value table.

\subsubsection{Example}

\begin{verbatim} --> portvalDINSPI 7F 00 00
portvalDINSPI=AAC03F
--> spitrDINSPI 7F0000 3FC0AA
Thermal flag    : 0
INT flag    : 0
SP0  - DIN0 : 1
SP1  - DIN1 : 1
SP2  - DIN2 : 1
SP3  - DIN3 : 1
SP4  - DIN4 : 1
SP5  - DIN5 : 1
SP6  - DIN6 : 1
SP7  - DIN7 : 1
SG0  - DIN8 : 0
SG1  - DIN9 : 1
SG2  - DIN10    : 0
SG3  - DIN11    : 1
SG4  - DIN12    : 0
SG5  - DIN13    : 1
SG6  - DIN14    : 0
SG7  - DIN15    : 1
SG8  - NA   : 0
SG9  - NA   : 0
SG10 - NA   : 0
SG11 - NA   : 0
SG12 - NA   : 0
SG13 - NA   : 0
spitrDINSPI=24\end{verbatim}

Translates response 0x3FC0AA returned by command 0x7F0000 into a human readable form. Please notice LSB-\mbox{$>$}MSB conversion of the portval result. The necessity of the conversion depends on the controller of the examined port.

\subsection{version}


Print version of the software

\subsubsection{Syntax}


version

\subsubsection{Description}


This command prints the version of the test software. The version number is the output of 'git describe' command, i.e. it is composed from the last tag in the git repository, the number of commits since the tag and the abbreviated commit hash.

\subsubsection{Example}

\begin{verbatim} --> version
version=v0.2-109-ga81a9dd\end{verbatim}

% html: End of file: `doc.html'
\chapter{Glossary}

\begin{description}
\item[ADC]
  \textit{Analog to Digital Converter.} \newline{}
  Hardware circuitry that converts a continuous physical quantity (usually voltage) to a
  digital number that represents the quantity's amplitude.

\item[AIN]
  \textit{Analog Input.} \newline{}
  Mnemonic to refer to or something related to the analog input (ADC) hardware module.

\item[AOUT]
  \textit{Analog Output.} \newline{}
  Mnemonic to refer to or something related to the analog output (DAC) hardware module.

\item[CAN]
  \textit{Controller Area Network.} \newline{}
  The CAN Bus is a vehicle bus standard designed to allow microcontrollers and devices to
  communicate with each other within a vehicle without a host computer.
  In this project it is also used as mnemonic to refer to or something related to the CAN
  hardware module.

\item[CGT]
  \textit{Code Generation Tools.} \newline{}
  Name given to the tool set produced by Texas Instruments used to compile, link, optimize,
  assemble, archive, among others. In this project is normally used as synonym for
  ``Texas Instruments ARM compiler and linker."

\item[DAC]
  \textit{Digital to Analog Converter.} \newline{}
  Hardware circuitry that converts a digital (usually binary) code to an analog signal
  (current, voltage, or electric charge).

\item[DIN]
  \textit{Digital Input.} \newline{}
  Mnemonic to refer to or something related to the digital input hardware module.

\item[ECU]
  \textit{Engine Control Unit.} \newline{}
  A type of electronic control unit that controls a series of actuators on an internal combustion
  engine to ensure the optimum running.

\item[ETH]
  \textit{Ethernet.} \newline{}
  Mnemonic to refer to or something related to the Ethernet hardware module.

\item[FR]
  \textit{FlexRay.} \newline{}
  FlexRay is an automotive network communications protocol developed to govern on-board automotive
  computing.
  In this project it is also used as mnemonic to refer to or something related to the FlexRay
  hardware module.

\item[GPIO]
  \textit{General Purpose Input/Output.} \newline{}
  Generic pin on a chip whose behavior (including whether it is an input or output pin) can be
  controlled (programmed) by the user at run time.

\item[HBR]
  \textit{H-Bridge.} \newline{}
  Mnemonic to refer to or something related to the H-Bridge hardware module. A H-Bridge is
  an electronic circuit that enables a voltage to be applied across a load in either direction.

\item[HOUT]
  \textit{High-Power Output.} \newline{}
  Mnemonic to refer to or something related to the 10A, PWM, with current sensing, high-power
  output hardware module.

\item[IDE]
  \textit{Integrated Development Environment.} \newline{}
  An IDE is a Software application that provides comprehensive facilities to computer programmers
  for software development.

\item[LCT]
  \textit{Legacy Code Tool.} \newline{}
  Matlab tool that allows to generate source code for S-Functions given the descriptor of a C 
  function call.

\item[LIN]
  \textit{Local Interconnect Network.} \newline{}
  The LIN is a serial network protocol used for communication between components in vehicles.
  In this project it is also used as mnemonic to refer to or something related to the LIN
  hardware module.

\item[LOUT]
  \textit{Logic Output.} \newline{}
  Mnemonic to refer to or something related to the digital output hardware module.
  It is logic output (100mA), as opposed to power outputs (2A, 10A).

\item[MBD]
  \textit{Model-Based Design.} \newline{}
  Model-Based Design (MBD) is a mathematical and visual method of addressing problems associated
  with designing complex control, signal processing and communication systems.

\item[MEX]
  \textit{Matlab Executable.} \newline{}
  Type of binary executable that can be called within Matlab. In this document the common term
  used is `C MEX S-Function", which means Matlab executable written in C that implements a system
  function.

\item[MOUT]
  \textit{(Motor) Power Output.} \newline{}
  Mnemonic to refer to or something related to the 2A push/pull power output hardware module.

\item[PWM]
  \textit{Pulse-width modulation.} \newline{}
  Technique for getting analog results with digital means. Digital control is used to create a
  square wave, a signal switched between on and off. This on-off pattern can simulate voltages
  in between full on and off by changing the portion of the time the signal spends on versus
  the time that the signal spends off. The duration of ``on time" is called the pulse width or
  \textit{duty cycle}.

\item[RPP]
  \textit{Rapid Prototyping Platform.} \newline{}
  Name of the automotive hardware board. Also generic term to define something related
  to the board, like the RPP Library, RPP Layer, RPP API, etc.

\item[SCI]
  \textit{Serial Communication Interface.} \newline{}
  Serial Interface for communication through hardware's UART using communication standard RS-232.
  In this project it is also used as mnemonic to refer to or something related to the Serial
  Communication Interface hardware module.

\item[SDC]
  \textit{SD-Card.} \newline{}
  Mnemonic to refer to or something related to the SD-Card hardware module.

\item[SDR]
  \textit{SD-RAM.} \newline{}
  Mnemonic to refer to or something related to the SD-RAM hardware module for logging.

\item[TLC]
  \textit{Target Language Compiler.} \newline{}
  Technology and language used to generate code in Matlab/Simulink.

\item[UART]
  \textit{Universal Asynchronous Receiver/Transmitter.} \newline{}
  Hardware circuitry that translates data between parallel and serial forms.
\end{description}


\chapter{References}

\begin{itemize}
\item Horn, M. (2013). \textit{Software obsluhující periferie a flexray na automobilové rídicí jednotce}.
  (Unpublished master's thesis, Czech Technical University in Prague, Prague, Czech Republic).

\item \textit{Model-based design}. (n.d.). In Wikipedia. Retrieved March 10, 2013, from \newline{}
  \htmladdnormallink{http://en.wikipedia.org/wiki/Model-based\_design}{http://en.wikipedia.org/wiki/Model-based\_design}

\item (2012). \textit{ARM Assembly Language Tools}. Texas Instruments.

\item (2012). \textit{ARM Optimizing C/C++ Compiler}. Texas Instruments.

\item (2013). \textit{Embedded Coder - Reference}. MathWorks.

\item (2013). \textit{Embedded Coder - User's Guide}. MathWorks.

\item Barry, R. (2009). \textit{Using the FreeRTOS real time kernel - A practical guide}.

\item (2013). \textit{Simulink Coder - Reference}. MathWorks.

\item (2013). \textit{Simulink - Target Language Compiler}. MathWorks.

\item (2013). \textit{Simulink Coder - User's Guide}. MathWorks.

\item (2013). \textit{Simulink - Developing S-Functions}. MathWorks.

\item (2012). \textit{TMS570LS31x/21x 16/32-Bit RISC Flash Microcontroller - Technical Reference Manual}.
  Texas Instruments.
\end{itemize}

\end{document}

%  LocalWords:  FreeRTOS RPP POSIX