[pes-rpp/rpp-simulink.git] / doc / reports / report / report.t2t

Final Report
Carlos Jenkins
%%date(%B, %Y)

%!target: tex
%!style(xhtmls): media/themes/Clean/style.css
%!postproc(xhtmls): 'NEWPAGE' ''
%!nested(xhtmls): --libs syntaxhighlighter
%!options(tex): --enum-title --toc --toc-level 5
%!postproc(tex): '\.pdf\.png' '.pdf'
%!postproc(tex): 'NEWPAGE' '\\newpage'
%!nested(tex): --docclass {article} --pdf

%S = Table of contents =[table_of_contents]

%Table of contents
%%toc

NEWPAGE


= Introduction =[introduction]

This document describes the final results of the project ``Code generation for automotive rapid prototyping 
platform using Matlab/Simulink".

The general layout of this document is as follows:

- Project description, objetives and outcome. This section.
- Software and Hardware setup for development and repository layout.
- Extensive description for each of the four products delivered.
- Glossary.
- References.
- Appendices.


== Background ==[background]

%DONE

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 has was built with automotive standards and interfaces in mind. It uses a real-time operating 
system and was directly programmed in C.

Nevertheless, in accordance to company policies 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:

        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.

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

NEWPAGE

== Technologies involved ==[technologies_involved]

%DONE

+ Matlab/Simulink data flow graphical programming language tool for modeling, simulating and analyzing 
  multidomain dynamic systems.
+ Standard ANSI C programming.
+ FreeRTOS real-time operating system.
+ Texas Instruments TI Code Generation Tools (CGT).
+ RPP in-house automotive hardware board using Texas Instruments TMS570LS3137 CPU.

== Objectives ==[objectives]

%DONE

Main objectives of this project are:

+ Allow C code generation from Matlab/Simulink models for custom made hardware platform.
+ Implement model blocks for some of the peripheral units of the board for use in Simulink programming.


At the time of this writing the objectives of this project are considered successfully achieved.

== Benefits ==[benefits]

%DONE

Expected benefits of this project are:

+ Enabling faster implementation and rapid-prototyping of Software components through the use of model-based 
  programming.
+ Enabling better and clearer visualization of Software implementations for the hardware board through models.
+ Improve auditability of Software system for automotive applications.


At the time of this writing the benefits of this project are considered enabled.

== Final outcome ==[final_outcome]

The main products generated for this project are:

- Simulink RPP Target.
- RPP Library and API.
- Simulink RPP Block Library.
- Simulink Demo Library.


Each of this product is described deeply in the following sections.

= Project setup =[project_setup]

This sections describes the Software and Hardware setup for development. It also describes the layout of the project
repository.

== Development environment ==[development_environment]

This section describes the Software setup for development.

=== Operating system ===[operating_system]

This project was developed on a GNU/Linux operating system. For development it is recommended to use a Debian based 
operating system for development as most of the tools are easily available from repositories. Relevant OS information 
is:

- Ubuntu 12.04.2 LTS AMD64.
- Kernel 3.2.0-48-generic.
- GCC version 4.6.3.


No test for cross-platform interoperability was performed on the code developed. Although care was taken to try to 
provide platform independent code and tools this are the elements that are know to be Linux dependent:

- LCM1 hardware control tool. @@
  This tool is both GUI and command line capable, the following just affects the GUI part. 
  Command line should be usable under Windows systems. @@
  __Cause__: Serial port search algorithm is Linux dependent and Gtk 3.0 dynamic Python bindings aren't available on 
  Windows operating systems.
- TI CGT support file for RPP Simulink Target ````target_tools.mk``". @@
  __Cause__: Use UNIX path separator ``/``.
- Simulink RPP Target download script ````rpp_download.m``". @@
  __Cause__: Use UNIX path separator ``/``.
- Simulink RPP Target install script ````rpp_setup.m``". @@
  __Cause__: Use UNIX path separator ``/``.
- Simulink RPP Block Library block compilation script ````compile_blocks.m``". @@
  __Cause__: Call Matlab MEX executable with Unix name.
- All CCS projects under ``<repo>/rpp/lib/apps/``. @@
  __Cause__: Paths are configure using UNIX path separator ``/``.



=== Version Control System ===[version_control_system]

The version control system used for this project is **git**. The repository of this project
contains all the files produced during development, including documentation, references, code and
graphics. Also the GUI application **gitk** was used to easily review changes. To install both
execute on a terminal:

{{{ bash
sudo apt-get install git gitk
}}}

=== TI Code Composer Studio ===[ti_code_composer_studio]

Code Composer Studio (CCS) is the official integrated development environment for developing applications 
for Texas Instruments embedded processors. CCS is multiplatform Software based on Eclipse Open Source IDE.

=== Matlab/Simulink ===[matlabsimulink]



=== GtkTerm ===[gtkterm]



=== Doxygen ===[doxygen]



=== Nested ===[nested]



=== LMC1 ===[lmc1]



== Hardware configuration ==[hardware_configuration]

Photo of the board

=== Modules description ===[modules_description]

Image of hardware modules.

==== Logic IO ====[logic_io]



===== 16x digital input (DIN) =====[16x_digital_input_din]

- Read status via GPIO pin (configurable threshold).
- Read status via SPI pin (fixed threshold).
- Setting pin programmable via SPI.


===== 8x digital outputs for loads up to 100 mA (LOUT) =====[8x_digital_outputs_for_loads_up_to_100_ma_lout]

- Set pin ON.
- Set pin OFF.
- Reading the SPI status excitation.

===== 12x analog-to-digital converter =====[12x_analog_to_digital_converter]

- Reading values on all channels.

===== 4x digital-to-analog converter =====[4x_digital_to_analog_converter]

- Set the required voltage on all channels.

==== Power Output ====[power_output]



===== 1x H-Bridge =====[1x_h_bridge]

- Setting the direction.
- Switch on, off.
- Communication with excitation by SPI.
- Enable PWM.


===== 6x outputs for loads up to 2 A (MOUT) =====[6x_outputs_for_loads_up_to_2_a_mout]

- Set pin ON.
- Set pin OFF.
- Reading diagnostics values (DIAG).

===== 6x output up to 10 A with PWM (HOUT) =====[6x_output_up_to_10_a_with_pwm_hout]

- Set pin ON.
- Set pin OFF.
- Reading analog values of current flowing (IFBK).
- Reading diagnostics values (DIAG).
- Detection of a fault condition.
- Turn on the PWM pin.

==== Communication ====[communication]



===== 3x CAN High speed =====[3x_can_high_speed]

- Sending and receiving messages between the CAN bus interfaces.
- Recover from error.
- Detection of network errors.

===== 2x LIN =====[2x_lin]

- Testing least one LIN using a loop. The second connector is shared with serial interface, which is tested alone communicate with the computer. Detailed testing makes sense to be no support for access to diagnostics unit via Ethernet or other interface.

===== 1x FlexRay =====[1x_flexray]

- Sending and receiving messages between two plates JRVA.


===== 1x Serial Comm. Interface =====[1x_serial_comm_interface]



===== 1x Ethernet =====[1x_ethernet]

- To send a packet.
- Code for testing Ethernet is the result of this thesis and is therefore not analyzed.

==== Data storage/logging ====[data_storagelogging]



===== External Memory SDRAM =====[external_memory_sdram]

- Determine the total capacity of the module fitted.
- Performing a memory test module using the entire address range.


===== SD Card =====[sd_card]



=== Development and test wiring ===[development_and_test_wiring]

How to wire the board for testing.

== Repository structure ==[repository_structure]


The repository is hosted on the server of the Real-Time Systems group at the Department
of Control Engineering

= Programming standards =[programming_standards]



== TLC files ==[tlc_files]



== RPP API ==[rpp_api]



== S-Functions ==[s_functions]



= Simulink RPP Target =[simulink_rpp_target]



== Description ==[description]



=== Code generation process ===[code_generation_process]



== Repository branch description ==[repository_branch_description]



== Installation procedure ==[installation_procedure]



== Target Reference ==[target_reference]

RPP Target Options
Simulink model options

= RPP Library and API =[rpp_library_and_api]



== Description ==[description]

Talk about motivation, work done and compare against origin.

=== Architecture ===[architecture]



=== Modules ===[modules]



=== OS interchangeable layer ===[os_interchangeable_layer]



=== Development guidelines ===[development_guidelines]

- Documentation in headers.
- Non-doxygen documentation in source code is intended for developpers, not users.
- Standard datatypes for IO when possible. Use custom structs as last resort.
- Prefix based functions names.
- To be careful about symbol export.

== Repository branch description ==[repository_branch_description]



== Test Suite ==[test_suite]



== Static libraries ==[static_libraries]



== Base application ==[base_application]



== API generation ==[api_generation]



== API Reference ==[api_reference]



= Simulink RPP Block Library =[simulink_rpp_block_library]



== Description ==[description]



=== C MEX S-Functions ===[c_mex_s_functions]

Anatomy
Compilation

=== Target Language Compiler files ===[target_language_compiler_files]

Anatomy

== Repository branch description ==[repository_branch_description]



== Block Reference ==[block_reference]



= Simulink Demos =[simulink_demos]



== Description ==[description]

Parameters
What was tested, resumen.

== Repository branch description ==[repository_branch_description]



== Demos Reference ==[demos_reference]



NEWPAGE

= Glossary =[glossary]

: ADC
  //Analog to Digital Converter.//
  Hardware circuitry that converts a continuous physical quantity (usually voltage) to a
  digital number that represents the quantity's amplitude.

: AIN
  //Analog Input.//
  Mnemonic to refer to or something related to the analog input (ADC) hardware module.

: AOUT
  //Analog Output.//
  Mnemonic to refer to or something related to the analog output (DAC) hardware module.

: CAN
  //Controller Area Network.//
  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.

: CGT
  //Code Generation Tools.//
  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."

: DAC
  //Digital to Analog Converter.//
  Hardware circuitry that converts a digital (usually binary) code to an analog signal
  (current, voltage, or electric charge).

: DIN
  //Digital Input.//
  Mnemonic to refer to or something related to the digital input hardware module.

: ECU
  //Engine Control Unit.//
  A type of electronic control unit that controls a series of actuators on an internal combustion 
  engine to ensure the optimum running.

: ETH
  //Ethernet.//
  Mnemonic to refer to or something related to the Ethernet hardware module.

: FR
  //FlexRay.//
  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.

: HBR
  //H-Bridge.//
  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.

: HOUT
  //High-Power Output.//
  Mnemonic to refer to or something related to the 10A, PWM, with current sensing, high-power
  output hardware module.

: IDE
  //Integrated Development Environment.//
  An IDE is a Software application that provides comprehensive facilities to computer programmers 
  for software development.

: LIN
  //Local Interconnect Network.//
  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.

: LOUT
  //Logic Output.//
  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).

: MBD
  //Model-Based Design.//
  Model-Based Design (MBD) is a mathematical and visual method of addressing problems associated 
  with designing complex control, signal processing and communication systems.

: MEX
  //Matlab Executable.//
  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.

: MOUT
  //(Motor) Power Output.//
  Mnemonic to refer to or something related to the 2A push/pull power output hardware module.

: RPP
  //Rapid Prototyping Platform//.
  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.

: SCI
  //Serial Communication Interface.//
  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.

: SDC
  //SD-Card.//
  Mnemonic to refer to or something related to the SD-Card hardware module.

: SDR
  //SD-RAM.//
  Mnemonic to refer to or something related to the SD-RAM hardware module for logging.

: TLC
  //Target Language Compiler.//
  Technology and language used to generate code in Matlab/Simulink.

: UART
  //Universal Asynchronous Receiver/Transmitter.//
  Hardware circuitry that translates data between parallel and serial forms.



NEWPAGE

= References =[references]

- Horn, M. (2013). //Software obsluhující periferie a flexray na automobilové rídicí jednotce//.
  (Unpublished master's thesis, Czech Technical University in Prague, Prague, Czech Republic).

- //Model-based design//. (n.d.). In Wikipedia. 
  Retrieved March 10, 2013, from http://en.wikipedia.org/wiki/Model-based_design


NEWPAGE

= Appendix A: Notes on FreeRTOS memory managment =[appendix_a_notes_on_freertos_memory_managment]

Write about heap implementation, FreeRTOSConfig.h heap size, C heap size, C stack size, Simulink memory, among others.