Matlab Wrapper

Matlab Wrapper is the AOCS framework extension developed for simple embedding of automatic generated control algorithms from the Matlab® into the particular framework instance of the AOCS framework.

The AOCS framework is determined for embedded applications and written in C++ and Java™ programming language, the Matlab Wrapper supports only an Embedded-C code format. The Embedded-C code format is optimized for speed and memory usage, shaped for real-time embedded systems generated by Real-Time Workshop Embedded Coder.

• Code Generation of a Control Algorithm
• Code Formats and Target Configuration
• Parameters: Interfacing, Tuning
• Signals: Interfacing, Tuning
• Generated Embedded-C Code
• Matlab Wrapper
• Design
• Java Implementation
• Verification & Example
• Requirements
• References
• API Specification
• Documentation

Code Generation of a Control Algorithm

 The paragraphs in the section 'Code Generation of a Control Algorithm' describe how to generate an Embedded-C code of a control block created in Matlab®/Simulink® environment that can be subsequently used in AOCS Framework.

Code Formats and Target Configuration

The Real-Time Workshop® offers  five different code formats. The Real-Time Code Format, Real-Time Malloc Code Format, S-function Format, Ada Format, and Embedded Code Format. Only the Embedded Code Format is designed for embedded applications. This format contains memory, performance optimizations and reduces code size. The memory is allocated only statically, dynamic memory allocation is not allowed.

Real-Time Workshop also supplies different target configurations. For our purposes is the most suitable the Real-Time Workshop Embedded  Coder Target that is consistent with the Embedded Code Format. 

For a generation of the optimized embedded code you have to set various options in the Simulation parameters item located in the Simulation menu. 

• In the Solver page of the Simulation Parameters dialog box you have to specify type of a solver. The Embedded Code Target requires a fixed-step discrete solver. 

• In the Advanced page you can select options that affect the performance of a generated code. The most important is the Model parameter configuration section where you specify how parameters will be represented in the generated code. To specify how will be parameters interfaced to externally written code you have to check the Inline parameters option and click on the button Configure (for other details see section Parameters: Interfacing, Tuning). In the Optimizations section you choose options that optimize memory usage an code size. We recommend to set the Block reduction option and Boolean logic signals option on.

• If in the section Category of the Real-Time Workshop page is set the item Target configuration then we can choose in the section Configuration one from a wide range of target configurations. We can use for our purposes only the RTW Embedded Coder. Since we are generally interested in generated code has to be this option in the Configuration section checked. 
  Under the item ERT code generation options in the section Category are hidden additional options. We recommend to check the following options: Initialize internal data, Initialize external I/O data, Terminate function required, and Single output/update function.  

• When are set all required options then click on the button Generate Code/Build located on the Real-Time Workshop page of the Simulation Parameters dialog box. The short overview about generated code you can find in a paragraph called Generated Embedded-C Code.

Parameters: Interfacing, Tuning

By default, block parameters are not tunable in the generated code. If you would like to set a block parameter as a tunable parameter (can be changed at run-time) you have to specify:

• The storage class of the parameter, where you can choose from four defined classes for tunable parameters (see below Fig. 1).


• SimulinkGlobal(Auto) - the default storage class (not sufficient for our purposes).
• ExportedGlobal - the generated code instantiates and initializes the parameter. The header file model_export.h (in our example testMatlabBlock_export.h) exports the parameter k as a global variable. In addition an exported global variable is initialized to the value of the corresponding workspace variable at code generation time. This storage class is highly recommended.
• ImportedExtern - the header file model.h (in our example testMatlabBlock.h) declares the parameter as an extern variable. The variable definition and initialization has to be done by the developer.
• ImportedExternPointer - the header file model.h (in our example testMatlabBlock.h) declares the parameter as an extern pointer. The developer has to provide the pointer variable definition and initializer.
  


• A storage type qualifier, such as const or volatile.

   

  Fig.1 Model Parameter Configuration

  The Model Parameter Configuration dialog can be found when you click on the Configure button placed on the Advanced page of the Simulation Parameters dialog box.
  
  For detailed description see Real-Time Workshop documentation from the page 3-51 to page 3-64.

   

Signals: Interfacing, Tuning

Real-Time Workshop has a number of options how to store input and output signals. We are mainly interested in a property which let us interface selected signals to externally writen code. The signal properties can be set from the Edit menu of a simulink model. This opens the Signal Properties dialog box (see below Fig. 2).

Fig.2 Signal Properties

To interface a signal to external code, assign one of the storage classes to the signal (see Fig.2):

• ExportedGlobal - the signal are stored in a global variable. The header file model_export.h (in our example testMatlabBlock_export.h) exports the variable. Signal must have unique signals names. This storage class is highly recommended.
• ImportedExtern - the header file model.h (in our example testMatlabBlock.h) declares the signal as an extern variable. The variable definition has to be done by the developer.
• ImportedExternPointer - the header file model.h (in our example testMatlabBlock.h) declares the signal as an extern pointer. The developer has to provide the pointer variable definition.

For detailed description see Real-Time Workshop documentation from the page 3-65 to page 3-78.

Generated Embedded-C Code

The Real-Time Workshop creates a new directory in the working directory to store generated source code. The name of the new directory is model_ert_rtw and contains the source code model.c and header files model_export.h , model.h, and autobuild.h, and the html documentation of the generated code.

Generated code also requires support header files which are stored in the directory matlabroot/rtw/c/ert. The support header files are following: ertformat.h, tmwtypes.h, simstruc_types.h, log_object.h, and log_macros.h.

For detailed description see Real-Time Workshop documentation pages 9-5 and 9-6.

Back To Top, Back to Real-Time Java Project Home

Matlab Wrapper for the AOCS Framework

The Matlab Wrapper is in the AOCS Framework a class called MatlabBlock, which sets various attributes and interfaces methods already  implemented by Real-Time Workshop.   

Design 

The design of the Matlab Wrapper heavily depends on the programming languages implementing the Matlab Wrapper. The output code format generated from Real-Time Workshop is optimized C code. Since we are focusing on porting the AOCS Framework to a real-time version of Java™,  the implementation of the MatlabWrapper has been done in Java™ language.

The generated code always contains the source code (e.g. model.c) with the same name as a model created in Simulink (e.g. model.mdl). The body of this source code contains the function model_step() implementing all computations for one time step, the function model_initialize() initializing the real-time object, and the function model_terminate() performing any cleanup operations. These three functions are the main entry points. The objective of the Matlab Wrapper is to interface these entry points and external variables representing tunable parameters and input/output signals as well.

Java Implementation of the Matlab Wrapper

The Matlab Wrapper implemented in Java™ language reperesents the class called MatlabBlock. The class MatlabBlock includes methods for an operation with particular instances. Methods calling a generated code by Real-Time Workshop are abstract methods, because their implementation is dependent on a particular block designed in the Matlab/Simulink environment. For example the class MatlabIntegratorBlock is an extension of the MatlabBlock that acts as the wrapper for a discrete integrator designed. In order to call the native code the Java Native Interface is used. An example of such concrete implementation is shown in the following section Verification & Testing. 

Verification & Testing

As an example for the testing and demostration of porting the generated code by Matlab/Real-TimeWorkshop has been chosen the discrete time integrator connected with the tunable gain.

The process consists of the following main steps:

1. Design of the control block in the Matlab/Simulink environment.
2. Code generation.
3. Native code incorporation - Java Native Interface (JNI).

A. Design of the control block in Matlab/Simulink environment

Matlab is well known high-performance language for technical computing, simulation, visualization and programming. Matlab offers large range of various packages that provide solutions for specific application domains. The packages are called toolboxes. 
Simulink is a special package (toolbox) for modeling, simulation, visualization of dynamical systems. Dynamical systems can be linear, nonlinear,  continues time systems, discrete time systems or hybrid systems. Simulink provides a rich graphical user interface for building models as block diagrams, just drag and drop operations.

As an example for the testing has been chosen the discrete time integrator connected with the tunable gain designed in the Matlab/Simulink environment. The name of the model is integr (See Fig.3).

Fig.3 Matlab model of the discrete integrator with the gain

B. Code generation

Before the code generation can start, a developer has to decide about tunable parameters, external inputs and outputs and set various options for the generation of the optimized code by Real-Time Workshop environment. All these important steps are described in the section Code Generation of a Control Algorithm.

• integr.c - defines all entry points to the generated code
• integr_export.h - defines the real-time object and provides a public interface to the entry points of the model code
• integr.h - defines parameters and data structures private to integr.c
• autobuild.h - generated only for use in test and simulation

Note: The source code mentioned above can be found in the downloadable project code, inside of the folder integr/GeneratedMatlabCode.

C. Native code incorporation - Java Native Interface (JNI)

Since the generated code has Embedded-C format and the AOCS Framework is written in Java™ language we need a mechanism that incorporate a native code in an application implemented in Java language. One possibility is to use mechanism called Java Native Interface (JNI). 

The Java Native Interface is a feature of the Java^TM platform. Already the first release of the Java Development Kit (JDK^TM) release 1.0 included a native method interface (NMI) that allowed to call functions written in C/C++. The JNI appeared for the first time in JDK™ release 1.1. The current version of the JDK called Java™ 2 SDK supports the old native method interface (NMI - originally implemented in JDK^TM 1.0), and also extends JNI to incorporate new features in the Java™ platform. JNI is a part of the Java™ platform, it means that the application with the incorporated native code will run on all implementations of the Java™ platform.

Using of the JNI will be demonstrated on the implementation of the Matlab Wrapper for the discrete time integrator block with the tunable gain. The process consists of the following steps:

1. Create a class (MatlabIntegratorBlock.java) that declares the native method.
2. Use javac to compile the MatlabIntegratorBlock source file, resulting in the class file MatlabIntegratorBlock.class.
3. Use javah -jni to generate a C header file (MatlabIntegratorBlock.h) containing the function prototype for the native method implementation.
4. Write the C/C++ implementation (MatlabIntegratorImp.cpp, MatlabIntegratorImp.h) of the native method.
5. Compile the C/C++ implementation into native library, creating matlabintegrator.dll (*.dll only for Win32 testing platform). Use the C/C++ compiler and linker available on the host environment.
6. Run the TestCaseMatlabBlock_2 testing program  using the java runtime interpreter. 

Note: The source code mentioned above can be found in the downloadable project code, inside of the folder integr.

• MatlabBlock.java - is the wrapper for the generated code by Real-Time Workshop
• MatlabIntegratorBlock.java - is the extension of the wrapper for the discrete integrator block with the tunable gain
• TestCaseMatlabBlock_2.java - testing of the wrapper
  

Back To Top, Back to Real-Time Java Project Home

Requirements for Generation of the Embedded-C Code Format

• Matlab 5.3, Simulink 3, Real-Time Workshop 3
• Real-Time Workshop Embedded Coder® is a part of the Real-Time Workshop
• Matlab 6, Simulink 4, Real-Time Workshop 4
• Real-Time Workshop Embedded Coder 1 is a separate product for use with the Real-Time Workshop
• Matlab 6.1, Simulink 4.1, Real-Time Workshop 4.1
• Real-Time Workshop Embedded Coder 2 is a separate product for use with the Real-Time Workshop
  

• Matlab 6, Simulink 4, Real-Time Workshop 4, Real-Time Workshop Embedded Coder 1
• Microsoft Visual Studio 6.0
• JBuilder 4 & Java™ 2 SDK
  

Back To Top, Back to Real-Time Java Project Home

References

API Specification

Sequential Data Processing Framelet 
Java Native Interface (JNI

Documentation

[1] The Mathworks Inc. - Matlab®
[2] The Mathworks Inc. - Simulink®
[3] The Mathworks Inc. - Real-Time Workshop®
[4] Sheng Liang - The Java Native Interface, Programmer's Guide and Specification
[5] The Java™ Tutrial - Java Native Interface