%!postproc(tex): '\.pdf\.png' '.pdf'
%!postproc(tex): 'NEWPAGE' '\\newpage'
%!postproc(tex): '-\$>\$' '\\noindent$\\rightarrow$'
+%!postproc(tex): 'TAB' '\\hspace{1.0em}'
%!nested(tex): --docclass {article} --pdf
%S = Table of contents =[table_of_contents]
= RPP Library and API =[rpp_library_and_api]
-
+%DONE
== Description ==[description]
+%DONE
The RPP Library is the support library used by Simulink models. It 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.
Some other relevant changes introduced with the refactoring are:
- ADC driver was completely rewritten.
-- MOUT driver was written.
+- MOUT driver was implemented.
- DIN driver was slightly modified and extended.
- DAC driver was slightly modified.
- HBR driver was largely modified (in particular watchdog functionality).
- SCI driver was refactored and extended.
+- SDR driver was implemented.
Also, once the library functionality could be isolated, the resulting API was too low-level to be used by
=== Architecture ===[architecture]
+%DONE
The RPP library was structured into 5 layers with the following guidelines:
- Top-down dependency only. No lower layer depends on anything from upper layers.
=== RPP Layer Modules ===[rpp_layer_modules]
+%DONE
The RPP Layer was structured into 14 different modules from 4 different categories that match the hardware
modules on the board:
=== OS interchangeable layer ===[os_interchangeable_layer]
+%DONE
The OS Layer is composed by the FreeRTOS source code files. Because the FreeRTOS exposes an stable
API the OS layer can be changed in order to upgrade the Operating System or use a different port of the
OS, without changing the upper layers source code. The OS Layers currently available for the RPP Library
=== API development guidelines ===[api_development_guidelines]
+%DONE
The following are the development guidelines use for developing the RPP API:
- User documentation should be placed in header files, not in source code, and should be Doxygen formatted
=== Further improvements ===[further_improvements]
+%DONE
The following are recommendations for future improvements of the library:
- General code revision to remove local-only methods and variables from being exported.
This are misleading.
-== Repository branch description ==[repository_branch_description]
+%S == Repository branch description ==[repository_branch_description]
+
-> ``apps/``
== Test Suite ==[test_suite]
+%DONE
The ``rpp-test-suite`` is a RPP application developed as part of this project that includes a series of
test tasks or test commands to verify the correct behavior and functionality of the RPP layer modules.
There is one command per module, and the command use the same mnemonic that the module.
=== AIN test description ===[ain_test_description]
+%DONE
This test will read all the analog inputs at a rate of 100 times per second and print the result.
```
=== AOUT test description ===[aout_test_description]
+%DONE
This test will generate a 10Hz sinus wave on all the analog outputs with a sampling rate of 1kHz.
The sinus wave of each analog output channel is sifted by (1/4)pi.
=== DIN test description ===[din_test_description]
+%DONE
This test will read all 16 + 8 the digital inputs at a rate of 100 times per second, using both low speed
SPI chip and variable threshold high-speed inputs.
=== HBR test description ===[hbr_test_description]
+%DONE
This test will generate a sinus wave to control the H-Bridge of one period per 20 seconds (0.05Hz) at a
sampling rate of 20Hz.
=== LOUT test description ===[lout_test_description]
+%DONE
This test will show in the digital outputs the value in binary of a counter, incrementing the counter
once per second. The counter is 8 bits, the same as the outputs, so 255 seconds are required for an
overflow/restart of the counting.
=== MOUT test description ===[mout_test_description]
+%DONE
This test will toggle the power outputs one by one per second, then wait 10 seconds in that state while
constantly verifying the diagnostics.
=== SCI test description ===[sci_test_description]
+%DONE
A more comprehensive test is not implemented. The very use of this test-suite implies the correct function
of the SCI module. Nevertheless, as a future improvement, a test that will verify run-time baud rate changes
and test some other RPP SCI functions is desirable.
=== SDR test description ===[sdr_test_description]
+%DONE
This test will launch a noise generator task that will log noise and then start the library included SD-RAM
logging command processor, allowing the user to see and handle the log on the SD-RAM.
== Static libraries ==[static_libraries]
+%DONE
The RPP Library can be compiled as a static library for ARM using TI CGT and for x86(_64) using GCC. CCS
projects ``rpp-lib`` and ``rpp-lib_posix`` in ``<repo>/rpp/lib/apps/`` allows to generate the static
libraries. After compilation, as part of the build process, both projects will automatically update the
== Base application ==[base_application]
+%DONE
In ``<repo>/rpp/lib/apps/`` there is two RPP base applications, ``base`` and ``base_posix``, that
already configured for the RPP Library. It is advised that new applications uses this projects a foundations.
== API generation ==[api_generation]
+%DONE
+The RPP Layer is formatted using Doxygen documentation generator. This allows to generate a high quality
+API reference. To generate the API reference do in a terminal:
-
+{{{ bash
+cd <repo>/rpp/lib/rpp/doc/api
doxygen doxygen.conf
+xdg-open html/index.html
+}}}
+
+The files under ``<repo>/rpp/lib/rpp/doc/api/content`` are used for the API reference generation are their
+name is self-explanatory:
+
+```
+blocks_map.html
+blocks.png
+cvut.png
+footer.html
+main_page.dox
+```
+
+To install Doxygen see [Development environment #development_environment] section.
== API Reference ==[api_reference]
+%DONE
+For the complete API reference please generate the HTML version using the above section instructions.
+Here is listed the index of functions of each module and their brief.
+
+Please note that not all modules were implemented as part of this project. See
+[RPP Layer Modules #rpp_layer_modules] for a list of the modules implemented.
+
+NEWPAGE
+
+=== DIN API Reference ===[din_api_reference]
+
+%DONE
+``int8_t rpp_din_init();`` @@ -> DIN module initialization. @@ @@
+``int8_t rpp_din_ref(uint16_t refA, uint16_t refB);`` @@ -> Configure voltage reference levels for digital inputs using variable reference threshold. @@ @@
+``int8_t rpp_din_setup(uint8_t pin, boolean_t pull_type, boolean_t active, boolean_t can_wake);`` @@ -> Configure given pin. @@ @@
+``int8_t rpp_din_get(uint8_t pin, boolean_t var_thr);`` @@ -> Get the current cached value of the given pin. @@ @@
+``int8_t rpp_din_diag(uint8_t pin);`` @@ -> Get the diagnostic cached value for given pin. @@ @@
+``int8_t rpp_din_update();`` @@ -> Read and update cached values and diagnostic values of all pins. Also commit configuration changes.
+
+=== LOUT API Reference ===[lout_api_reference]
+
+%DONE
+``int8_t rpp_lout_init();`` @@ -> LOUT module initialization. @@ @@
+``int8_t rpp_lout_set(uint8_t pin, uint8_t val);`` @@ -> Set the output cache of given pin to given value. @@ @@
+``int8_t rpp_lout_diag(uint8_t pin);`` @@ -> Get the diagnostic cached value for given pin. @@ @@
+``int8_t rpp_lout_update();`` @@ -> Flush cached output values and read back diagnostic values of all pins.
+
+=== AIN API Reference ===[ain_api_reference]
+
+%DONE
+``int8_t rpp_ain_init();`` @@ -> AIN module initialization. @@ @@
+``int16_t rpp_ain_get(uint8_t pin);`` @@ -> Get the current analog value on the given pin. @@ @@
+``int8_t rpp_ain_update();`` @@ -> Read and update analog cached values.
+
+
+=== AOUT API Reference ===[aout_api_reference]
+
+%DONE
+``#define RPP_DAC_OA 5.6`` @@ -> DAC output operational amplifier multiplication constant. @@ @@
+``#define RPP_DAC_VREF 2.5`` @@ -> DAC hardware reference voltage. @@ @@
+``int8_t rpp_aout_init();`` @@ -> AOUT module initialization. @@ @@
+``int8_t rpp_aout_setup(uint8_t pin, boolean_t enabled);`` @@ -> Configure enabled/disabled state for given pin. @@ @@
+``int8_t rpp_aout_set(uint8_t pin, uint16_t val);`` @@ -> Set the output cache of given pin to given value. @@ @@
+``int8_t rpp_aout_set_voltage(uint8_t pin, uint16_t mv);`` @@ -> Set output to given voltage. @@ @@
+``int8_t rpp_aout_update();`` @@ -> Flush cached output values and configuration changes.
+
+=== HBR API Reference ===[hbr_api_reference]
+
+%DONE
+``int8_t rpp_hbr_init();`` @@ -> HBR module initialization. @@ @@
+``int8_t rpp_hbr_enable(int32_t period);`` @@ -> Enable the H-Bridge for control. @@ @@
+``int8_t rpp_hbr_control(double cmd);`` @@ -> Control the H-Bridge direction, enabled/disabled and PWM. @@ @@
+``int8_t rpp_hbr_disable();`` @@ -> Disable the H-Bridge.
+
+NEWPAGE
+
+=== MOUT API Reference ===[mout_api_reference]
+
+%DONE
+``int8_t rpp_hbr_init();`` @@ -> HBR module initialization. @@ @@
+``int8_t rpp_mout_init();`` @@ -> MOUT module initialization. @@ @@
+``int8_t rpp_mout_set(uint8_t pin, uint8_t val);`` @@ -> Set the output of given pin to given value. @@ @@
+``int8_t rpp_mout_get(uint8_t pin);`` @@ -> Get the cached value of the given pin set by rpp_mout_set(). @@ @@
+``int8_t rpp_mout_diag(uint8_t pin);`` @@ -> Reads the value on the given diagnostic pin.
+
+=== HOUT API Reference ===[hout_api_reference]
+
+%DONE
+``int8_t rpp_hout_init();`` @@ -> HOUT module initialization.
+
+=== CAN API Reference ===[can_api_reference]
+
+%DONE
+``int8_t rpp_can_init();`` @@ -> CAN module initialization.
+
+=== LIN API Reference ===[lin_api_reference]
+
+%DONE
+``int8_t rpp_lin_init();`` @@ -> LIN module initialization.
+
+=== FR API Reference ===[fr_api_reference]
+
+%DONE
+``int8_t rpp_fr_init();`` @@ -> FR module initialization.
+
+NEWPAGE
+
+=== SCI API Reference ===[sci_api_reference]
+
+%DONE
+``int8_t rpp_sci_init();`` @@ -> SCI module initialization. @@ @@
+``boolean_t rpp_sci_setup(uint32_t baud);`` @@ -> SCI module setup. @@ @@
+``uint16_t rpp_sci_available();`` @@ -> Number of bytes available on input buffer. @@ @@
+``int8_t rpp_sci_read(uint32_t amount, uint8_t* buffer);`` @@ -> Read n number of bytes from input buffer. @@ @@
+``int8_t rpp_sci_read_nb(uint32_t amount, uint8_t* buffer);`` @@ -> Read n number of bytes from input buffer if possible. @@ @@
+``int8_t rpp_sci_write(uint32_t amount, uint8_t* data);`` @@ -> Write n number of bytes to the output buffer. @@ @@
+``int8_t rpp_sci_write_nb(uint32_t amount, uint8_t* data);`` @@ -> Write n number of bytes to the output buffer if possible. @@ @@
+``int8_t rpp_sci_flush(boolean_t buff);`` @@ -> Flush incomming or outgoing buffers. @@ @@
+``int32_t rpp_sci_printf(const char* format, ...);`` @@ -> C style printf using RPP SCI module. @@ @@
+``int8_t rpp_sci_putc(uint8_t byte);`` @@ -> C style putc (put character) using RPP SCI module. @@ @@
+``int16_t rpp_sci_getc();`` @@ -> C style getc (get character) using RPP SCI module.
+
+=== ETH API Reference ===[eth_api_reference]
+
+%DONE
+``int8_t rpp_eth_init();`` @@ -> ETH module initialization.
+
+=== SDC API Reference ===[sdc_api_reference]
+
+%DONE
+``int8_t rpp_sdc_init();`` @@ -> SDC module initialization.
+
+=== SDR API Reference ===[sdr_api_reference]
+
+%DONE
+``#define RPP_SDR_ADDR_START 0x80000000U`` @@ -> SDRAM start address on RPP board. @@ @@
+``#define RPP_SDR_ADDR_END 0x83FFFFFFU`` @@ -> SDRAM end address on RPP board. @@ @@
+``int8_t rpp_sdr_init();`` @@ -> SDR module initialization. @@ @@
+``int8_t rpp_sdr_setup(boolean_t enable);`` @@ -> Configure SD-RAM logging. @@ @@
+``uint32_t rpp_sdr_available();`` @@ -> Query for the amount of space free on the SD-RAM. @@ @@
+``int32_t rpp_sdr_printf(const char* format, ...);`` @@ -> Store a formatted user string on the log, if logging is enabled. @@ @@
+``int8_t rpp_sdr_clear();`` @@ -> Clear log. @@ @@
+``int8_t rpp_sdr_show(boolean_t start);`` @@ -> Start/Stop the task that sends the log to the SCI.
NEWPAGE
[530-block_library.png]
%tex% ''' \caption{Simulink RPP Block Library.}\end{figure}
-=== [LOUT] Digital Output block ===[lout_digital_output_block]
+NEWPAGE
+
+=== DIN Digital Input block ===[din_digital_input_block]
+
+```
+ Inputs : 0
+ None
+
+ Outputs : 2
+ bool Digital Input
+ bool ErrFlag
+
+ Parameters : 2
+ uint8 Pin number [1-16]
+ bool Use variable threshold
+```
+
+This block allows to read the digital inputs on the RPP board. The variable threshold check change the read
+mode of the pin (from the block size this is working, library call is not working though). The ErrFlag should
+raise if ``rpp_din_update()`` or ``rpp_din_get()`` returns error. ``rpp_din_update()`` is called just by the
+first DIN block in the model and thus only the first block could raise the flag because of this. In case an
+errors occurs the return value will always be LOW (0).
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_din_setup()``.
+- ``rpp_din_update()``.
+- ``rpp_din_get()``.
+
+
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``hbridge_digital_control``.
+
+
+NEWPAGE
+
+=== LOUT Digital Output block ===[lout_digital_output_block]
+
+```
+ Inputs : 1
+ bool Digital Output
+
+ Outputs : 1
+ bool ErrFlag
+
+ Parameters : 1
+ uint8 Pin number [1-8]
+```
+
+This block allows to write to the digital outputs on the RPP board. The ErrFlag should raise if ``rpp_lout_set()``
+or ``rpp_lout_update()`` returns error. ``rpp_lout_update()`` is called on each block, which is not the most
+efficient but guaranties consistent behavior.
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_lout_set()``.
+- ``rpp_lout_update()``.
+
+
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``led_blink_all``.
+- ``led_blink``.
+
+
+NEWPAGE
+
+=== AIN Analog Input block ===[ain_analog_input_block]
+
+```
+ Inputs : 0
+ None
+
+ Outputs : 2
+ uint16 Analog Input
+ bool ErrFlag
+
+ Parameters : 1
+ uint8 Pin number [1-12]
+```
+
+This block allows to read the analog inputs on the RPP board. The ErrFlag should if raise ``rpp_ain_update()``
+or ``rpp_ain_get()`` returns error. ``rpp_ain_update()`` is called just by the first DIN block in the model and
+thus only the first block could raise the flag because of this. In case an errors occurs the return value will
+always be 0.
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_ain_update()``.
+- ``rpp_ain_get()``.
+
+
+**Demos that uses this block:**
+- ``analog_passthrough``.
+- ``hbridge_analog_control``.
+- ``log_analog_input``.
+
+
+NEWPAGE
+
+=== AOUT Analog Output block ===[aout_analog_output_block]
+
+```
+ Inputs : 1
+ uint16 Analog Output
+
+ Outputs : 1
+ bool ErrFlag
+
+ Parameters : 1
+ uint8 Pin number [1-4]
+ bool Use voltage
+```
+
+This block allows to read the digital inputs on the RPP board. The variable threshold check change the read
+mode of the pin (from the block size this is working, library call is not working though). The ErrFlag should
+raise ``rpp_din_update()`` or ``rpp_din_get()`` returns error. ``rpp_din_update()`` is called juts by the
+first DIN block in the model and thus only the first block could raise the flag because of this.
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_din_setup()``.
+- ``rpp_din_update()``.
+- ``rpp_din_get()``.
+
+
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``hbridge_digital_control``.
+
+
+=== HBR H-Bridge Control block ===[hbr_h_bridge_control_block]
+
+```
+ Inputs : 1
+ double Control
+
+ Outputs : 1
+ bool ErrFlag
+
+ Parameters : 0
+ None
+```
+
+This block allows to read the digital inputs on the RPP board. The variable threshold check change the read
+mode of the pin (from the block size this is working, library call is not working though). The ErrFlag should
+raise ``rpp_din_update()`` or ``rpp_din_get()`` returns error. ``rpp_din_update()`` is called juts by the
+first DIN block in the model and thus only the first block could raise the flag because of this.
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_din_setup()``.
+- ``rpp_din_update()``.
+- ``rpp_din_get()``.
+
+
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``hbridge_digital_control``.
+
+
+=== MOUT Power Output block ===[mout_power_output_block]
+
+```
+ Inputs : 1
+ bool Power Output
+
+ Outputs : 1
+ bool ErrFlag
+
+ Parameters : 1
+ uint8 Pin number [1-6]
+```
+
+This block allows to read the digital inputs on the RPP board. The variable threshold check change the read
+mode of the pin (from the block size this is working, library call is not working though). The ErrFlag should
+raise ``rpp_din_update()`` or ``rpp_din_get()`` returns error. ``rpp_din_update()`` is called juts by the
+first DIN block in the model and thus only the first block could raise the flag because of this.
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_din_setup()``.
+- ``rpp_din_update()``.
+- ``rpp_din_get()``.
+
+
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``hbridge_digital_control``.
+
+
+=== SCIR Serial Comm. Interface Receive ===[scir_serial_comm_interface_receive]
+
+```
+ Inputs : 0
+ None
+
+ Outputs : 2
+ uint8 Data
+ bool ErrFlag
+
+ Parameters : 0
+ None
+```
+
+This block allows to read the digital inputs on the RPP board. The variable threshold check change the read
+mode of the pin (from the block size this is working, library call is not working though). The ErrFlag should
+raise ``rpp_din_update()`` or ``rpp_din_get()`` returns error. ``rpp_din_update()`` is called juts by the
+first DIN block in the model and thus only the first block could raise the flag because of this.
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_din_setup()``.
+- ``rpp_din_update()``.
+- ``rpp_din_get()``.
+
+
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``hbridge_digital_control``.
+
+
+=== SCIS Serial Comm. Interface Send ===[scis_serial_comm_interface_send]
+
+```
+ Inputs : 1
+ uint8 Data
+
+ Outputs : 1
+ bool ErrFlag
+
+ Parameters : 2
+ bool UsePrintf
+ string PrintFormat [SETTING]
+```
+
+This block allows to read the digital inputs on the RPP board. The variable threshold check change the read
+mode of the pin (from the block size this is working, library call is not working though). The ErrFlag should
+raise ``rpp_din_update()`` or ``rpp_din_get()`` returns error. ``rpp_din_update()`` is called juts by the
+first DIN block in the model and thus only the first block could raise the flag because of this.
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_din_setup()``.
+- ``rpp_din_update()``.
+- ``rpp_din_get()``.
+
+
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``hbridge_digital_control``.
+
+
+=== SCIC Serial Comm. Interface Configure ===[scic_serial_comm_interface_configure]
+
+```
+ Inputs : 0
+ None
+
+ Outputs : 0
+ None
+
+ Parameters : 1
+ uint32 Baud rate
+```
+
+This block allows to read the digital inputs on the RPP board. The variable threshold check change the read
+mode of the pin (from the block size this is working, library call is not working though). The ErrFlag should
+raise ``rpp_din_update()`` or ``rpp_din_get()`` returns error. ``rpp_din_update()`` is called juts by the
+first DIN block in the model and thus only the first block could raise the flag because of this.
+
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
+
+
+**RPP API functions used:**
+- ``rpp_din_setup()``.
+- ``rpp_din_update()``.
+- ``rpp_din_get()``.
+
+
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``hbridge_digital_control``.
+
+
+=== SDRW SD-RAM Write ===[sdrw_sd_ram_write]
+
+```
+ Inputs : 1
+ double Data
+
+ Outputs : 1
+ bool ErrFlag
+
+ Parameters : 2
+ uint8 Block ID
+ string PrintFormat [SETTING]
+```
+
+This block allows to read the digital inputs on the RPP board. The variable threshold check change the read
+mode of the pin (from the block size this is working, library call is not working though). The ErrFlag should
+raise ``rpp_din_update()`` or ``rpp_din_get()`` returns error. ``rpp_din_update()`` is called juts by the
+first DIN block in the model and thus only the first block could raise the flag because of this.
+
+**Status:**
+|| Tested | Untested | Not working
+ | Changing the pin. | Faulty situation for the ErrFlag to set. | Using variable threshold. |
+ | Compilation and general use. | | |
-=== [DIN] Digital Input block ===[din_digital_input_block]
+**RPP API functions used:**
+- ``rpp_din_setup()``.
+- ``rpp_din_update()``.
+- ``rpp_din_get()``.
-- Inputs : 0
- - None
-- Outputs : 2
- - ``bool`` Digital Input
- - ``bool`` ErrFlag
-- Parameters : 2
- - ``uint8`` Pin number [1-16]
- - ``bool`` Use variable threshold
+**Demos that uses this block:**
+- ``digital_passthrough``.
+- ``hbridge_digital_control``.
-Description.
-Implementation notes.
-On top of what was built.
-Relevant demos.
-Tested.
= Simulink Demos =[simulink_demos]
projects / jenkicar / rpp-simulink.git / commitdiff