[pes-rpp/rpp-simulink.git] / doc / reports / report1 / publish / tex / report1.tex

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

\documentclass{article}

\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[utf8]{inputenc}  % char encoding
\usepackage[bottom]{footmisc} % footnotes

% 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
\addtolength{\parskip}{\baselineskip} % Paragraph 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}

\begin{document}

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

\begin{titlepage}
\begin{center}

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


% Document title
\HRule \\[0.4cm]
{ \huge \bfseries Progress report 1}\\[0.4cm]
\HRule \\[1.5cm]


% Author
\emph{Author:}\\
Carlos \textsc{Jenkins}\\

\vfill

% Bottom of the page
{\large \today}

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

\tableofcontents

\newpage

\hypertarget{introduction}{}
\section{Introduction}

This document describes the first progress report for the project ``Code generation for automotive 
rapid prototyping platform using Matlab/Simulink" executed on the first semester of 2013 at the 
Department of Control Engineering, Faculty of Electrical Engineering, Czech Technical University, 
as part of the specialty practice for applying for the Computer Engineering Bachelor degree at the 
Costa Rica Institute of Technology.

This report aims to outline the context, risks, goals and scope of the project and to describe
the system to develop.

\hypertarget{project_context}{}
\section{Project context}

This section describes the institution where the project is held and the background of the project.

\hypertarget{institution}{}
\subsection{Institution}

The project is being held at the Real-Time Systems group, Department of Control Engineering,
Faculty of Electrical Engineering from the Czech Technical University in Prague.

The head of the department is Dr. Zdeněk Hanzálek, Director Industrial Informatics Group, 
Department of Control Engineering, Faculty of Electrical Engineering, Czech Technical University 
in Prague.

Professor Assistant Ing. Michal Sojka Ph.D., Department of Control Engineering, Faculty of 
Electrical Engineering, Czech Technical University in Prague, will held as supervisor of the 
project.

\hypertarget{background}{}
\subsection{Background}

Back in the beginning of 2012 a leading automotive company requested the Czech Technical University
to develop a Engine Control Unit (ECU) for automotive applications. Real-Time Systems group at the
Department of Control Engineering from the Faculty of Electrical Engineering developed a hardware
and Software platform to the needs of this industry. The hardware uses Texas Instruments
TMS570LS3137 CPU and is built with automotive standards and interfaces in mind. It uses a real-time
operating system and was directly programmed in C.

As will later be described, the automotive company needs to program such board in a different
environment.

\hypertarget{problem_description}{}
\section{Problem description}

This section describes the problem faced with this project and the solution aimed.

\hypertarget{problem_statement}{}
\subsection{Problem statement}

The board is programmed using hand written C code. This approach faces the following problems about 
the code:

\begin{compactitem}
\item It is hard to produce, sometimes very low-level.
\item It is hard to debug. Yes, 1 bit took us 4 hours.
\item It requires good knowledge of the underlying hardware.
\item Most of the time is non-portable or hard to port between platforms.
\item It is hard to audit and certify. 
\end{compactitem}

In consequence, the automotive company established policies that stipulate that the Software 
developed for the engine control unit must be designed in a safe and auditable way. The company has 
the policy to implement the Software for their system using Model-Based Design:

        \begin{quotation}
Model-Based Design (MBD) is a mathematical and visual method of addressing
problems associated with designing complex control, signal processing and
communication systems. It is used in many motion control, industrial equipment,
aerospace, and automotive applications. Model-based design is a methodology
applied in designing embedded software.
        \end{quotation}

In order to meet this requirement an interaction layer between the platform and the Software the
company uses, Matlab/Simulink, must be implemented.

\hypertarget{solution_statement}{}
\subsection{Solution statement}

The solution for project problem is to implement and Simulink target that allows models to generate 
code for the board. Such models needs to interact with board peripherals and in consequence driver 
blocks need to be implemented too. Finally, driver blocks need to generate code on top of a well 
tested C support library that include drivers and Operating System for the board.

\hypertarget{project_stackeholders}{}
\subsection{Project stackeholders}

Main project stackeholders are:

\begin{enumerate}
\item Dr. Zdeněk Hanzálek. Director Industrial Informatics Group, Department of Control Engineering, 
  Faculty of Electrical Engineering, Czech Technical University in Prague. As director of the 
  department, Dr. Hanzálek has no direct responsibility on the project but has direct 
  responsibility on the success oof the main project. \newline{}
  Main interest of Dr. Hanzálek is the success of the project in order to enable the success of the
  mother project (board development for automotive applications) and to maintain the high prestige
  and confidence the industry has over the department and the university.

\item Ing. Michal Sojka Ph.D. Professor Assistant, Department of Control Engineering, Faculty of 
  Electrical Engineering, Czech Technical University in Prague. CVUT project supervisor, 
  co-responsible for grade the student. \newline{}
  Ing. Sojka main interest in the project is the success and implementation of the solution.

\item Prof. Jeff Schmidt Peralta. Computer Engineering Professor, Faculty of Computer Engineering,
  Costa Rica Institute of Technology. ITCR project supervisor, co-responsible for grade the 
  student. \newline{}
  Prof. Schmidt main interest is the success of the project in order to enable student to opt-out 
  for Bachelor degree and to maintain and develop the high prestige the university currently held.
\end{enumerate}

\hypertarget{summary_of_needs_and_expectations}{}
\subsection{Summary of needs and expectations}

Project needs are summarized as:

\begin{compactenum}
\item To have a fully automatic and tested system for Simulink models code generation, build and code 
  download to the hardware board.
\item To have a fully tested C support library for those models to link to.
\item To have a set of Simulink driver blocks that allows models to interact with the hardware 
  peripherals.
\end{compactenum}

Expected benefits of this project are:

\begin{compactenum}
\item Enabling faster implementation and rapid-prototyping of Software components through the use of
  model-based programming.
\item Enabling better and clearer visualization of Software implementations for the hardware board
  through models.
\item Improve auditability of Software system for automotive applications.
\end{compactenum}

\hypertarget{perspective_assumptions_and_product_dependencies}{}
\subsection{Perspective, assumptions and product dependencies}

The main assumptions for the project are:

\begin{compactitem}
\item Drivers work and are tested.
\item Hardware works and is tested.
\end{compactitem}

Main dependencies for the system to develop are:

\begin{compactitem}
\item A functional board.
\item For each deliverable previous deliverable is required to work and be tested in order to implement
  the new deliverable. This dependency over the previous product makes the project very dificult to 
  develop in parallel. The following arrows show system dependency: \newline{}
  Demos \noindent$\rightarrow$ Block Library \noindent$\rightarrow$ Target \noindent$\rightarrow$ Support Library.
\end{compactitem}

\hypertarget{non_functional_requirements}{}
\subsection{Non-functional requirements}

Two main requirements are stipulated according automotive safety policies:

\begin{compactitem}
\item The use of a real-time Operating System is mandatory.
\item Application should be real-time and guarantee to respond in one Operating System tick time.
\item All memory should be statically allocated, there should never be dynamically allocated memory.
\end{compactitem}

\hypertarget{risk_analysis}{}
\section{Risk analysis}

This section describes the risk that could be encountered during the execution of the project
and the containment and evasion strategies considered.

\hypertarget{unkown_development_environment_and_tools}{}
\subsection{Unkown development environment and tools}

This is the most important risk for the project and involves the lack of technical knowledge and
the introduction of the student to a completely new environment, API, processes, tools, hardware 
and code base. The student is has never being exposed to any of the tools in the environment with 
exception of C embedded development.

\begin{compactitem}
\item \textbf{Category:} people.
\item \textbf{Possible cause}: lack of technical knowledge.
\item \textbf{Impact for the project}: 100.
\item \textbf{Probability to happen}: 1.0.
\item \textbf{Exposition to risk}: 100 * 1.0 = 100\%.
\item \textbf{Evasion strategy}:
 \begin{compactitem}
 \item This risk cannot be evaded.
 \end{compactitem}
\item \textbf{Mitigation strategy}: 
 \begin{compactitem}
 \item Read technical documentation about tools.
 \item Read existing code base.
 \item Learn to use new development tools.
 \item Document every aspect of the use.
 \item Learn to use, manipulate and understand the hardware.
 \end{compactitem}
\end{compactitem}

\newpage

\hypertarget{board_malfunction}{}
\subsection{Board malfunction}

\begin{compactitem}
\item \textbf{Category:} infrastructure.
\item \textbf{Possible cause}: hardware error, mishandling or environment.
\item \textbf{Impact for the project}: 80.
\item \textbf{Probability to happen}: 0.5.
\item \textbf{Exposition to risk}: 80 * 0.5 = 40\%.
\item \textbf{Evasion strategy}:
 \begin{compactitem}
 \item Board should always be handled in a safe manner, using anti-static methods.
 \item Connection 
 \item Power supply connections will always be double checked.
 \item Environment around the board and board connections will be checked twice before powering on the 
   board.
 \end{compactitem}
\item \textbf{Mitigation strategy}: 
 \begin{compactitem}
 \item Ask to supervisor to check the problem.
 \item Replace development board to another available board. Very expensive choice.
 \end{compactitem}
\end{compactitem}

\hypertarget{goals_and_system_scope}{}
\section{Goals and system scope}

This section describes the goals and scope of the project.

\hypertarget{objectives}{}
\subsection{Objectives}

Main objectives of this project are:

\begin{compactenum}
\item Allow C code generation from Matlab/Simulink models for custom made hardware platform.
\item Implement model blocks for some of the peripheral units of the board for use in Simulink 
  programming.
\end{compactenum}

\hypertarget{specific_objectives}{}
\subsection{Specific objectives}

Specific objectives of this project are:

\begin{compactenum}
\item Implementation of a C support library that defines an API that can be called by Simulink blocks.
  The support library should include a test suite that allows to test and confirm the correct 
  behavior of the library.
\item Implementation of a Simulink Coder Target for the RPP board that uses the CGT compiler.
\item Implementation of a Simulink Block Library that includes the main block drivers for the RPP 
  board.
\item Implementation of a set of demos that illustrates the use of the system and confirms the correct 
  behavior of the implementation.
\end{compactenum}

\hypertarget{system_scope}{}
\subsection{System scope}

For the C support library, the test suite of such library and the block library should limit to
the following hardware modules:

\begin{multicols}{2}

\begin{compactitem}
\item DIN.
\item LOUT.
\item AIN.
\item AOUT.
\item HBR.
\item MOUT.
\item SCI.
\item SDR.
\end{compactitem}

\end{multicols}

\hypertarget{development_inputs}{}
\section{Development inputs}

This section describes conceptual inputs for development.

\hypertarget{use_case_diagram}{}
\subsection{Use case diagram}

This project is focused in embedded Software development in a non-object oriented programming
language and thus is not driven with a Use Case methodology. In consequence, this section does not 
apply.

\hypertarget{use_cases_specification}{}
\subsection{Use cases specification}

This project is focused in embedded Software development in a non-object oriented programming
language and thus is not driven with a Use Case methodology. In consequence, this section does not 
apply.

\hypertarget{domain_conceptual_model}{}
\subsection{Domain conceptual model}

\begin{figure}[H]\begin{center}

\noindent\includegraphics[width=400px]{media/images/tlc_process.png}
\caption{Conceptual code generation process.}\end{center}\end{figure}

\newpage

\hypertarget{glossary}{}
\subsection{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}

\newpage

\hypertarget{work_schedule}{}
\section{Work schedule}

\begin{center}\begin{tabular}{|c|c|l|}
\hline \textbf{Date} & \textbf{Deliverable} & \textbf{Priority} \\
\hline \multicolumn{1}{|l|}{15.4.2013} & \multicolumn{1}{|l|}{C support library and test suite.} & \multicolumn{1}{|c|}{1} \\
\hline \multicolumn{1}{|l|}{01.5.2013} & \multicolumn{1}{|l|}{Simulink Coder target for RPP board.} & \multicolumn{1}{|c|}{2} \\
\hline \multicolumn{1}{|l|}{01.6.2013} & \multicolumn{1}{|l|}{Simulink Block library. S-Functions and TLC files.} & \multicolumn{1}{|c|}{3} \\
\hline \multicolumn{1}{|l|}{07.6.2013} & \multicolumn{1}{|l|}{Simulink Demo  library.} & \multicolumn{1}{|c|}{4} \\
\hline \multicolumn{1}{|l|}{21.6.2013} & \multicolumn{1}{|l|}{Finish documentation of the developed product.} & \multicolumn{1}{|c|}{5} \\
\hline \end{tabular}\end{center}

\end{document}