User Guide
OpenECU Developer Platform
Sim-API

The following items of hardware are available as part of OpenECU:

The following items of software are available as part of OpenECU:

And the following items of software are required but not provided as part of OpenECU.

To run the Pi OpenECU software with MATLAB and Simulink, you will need an IBM-compatible PC with the minimum specifications listed below. These specifications are the same as those for running MATLAB:

Either the physical system or a system simulator, is ultimately required to test and calibrate your ECU and the system model you have created to run on it. A suitable Calibration/reprogramming communications tool is also required conforming to the ASAP2 standard.

You will need the following software pre-installed on your PC:

See the Chapter 2, Installation for full details of the software required.

This manual describes how to incorporate the OpenECU Simulink blocks provided by Pi Innovo into your own designs, but does not include a MATLAB or Simulink guide or tutorial. Please refer to the user guides that accompany that software for full installation and operating instructions.

A working knowledge of design modelling and system dynamics principles in an engineering environment is required to make the best use of Simulink and OpenECU. Ultimately, it is the quality of your own system designs that will be reflected in the quality of your system control strategy.

Note also that there are serious hardware and personal safety considerations involved in developing automotive control systems. Please make sure that you read and understand the Safety and Warning section at the end of this chapter to reduce the chance of any such hazards.

Pi Innovo considers the safety and quality of its products to be of paramount importance. The integrity of the product can be considered by assessing the three 'components' which comprise the system.

Systems, rather than software, have a Safety Integrity Level (SIL). The SIL of the customer's resultant system will have to be assessed and defined by their knowledge of the processes used to develop all the components (including those supplied by Pi) comprising the complete system.

The process of testing automotive systems can involve many personal safety hazards — high-speed machinery, extremely flammable and potentially explosive fuels, and the possibility of loss of vehicle control is a combination that can be fatal if sensible precautions are not followed.

As the system designer and tester, it is your responsibility to ensure that your working practices are specifically designed to minimise or eliminate the possibility of personal injury, and to incorporate into your designs such fail-safe functionality as is necessary. This includes the avoidance of certain dynamical situations such as open throttles and other 'positive feedback' scenarios where control of the system may be lost.

Pi Innovo makes no representation or warranties of any kind whatsoever with respect to the contents hereof, and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Pi Innovo shall not be liable for any errors contained herein, or for incidental or consequential damages in connection with the furnishing, performance or use of the software, associated hardware, or this written material.

Pi Innovo reserves the right to revise this publication from time to time, and to make changes in the content hereof without obligation to notify any person of such revision or changes.

A copy of the Pi Innovo Terms and Conditions of Sale is available on request, and includes a declaration of the warranty and limitation of liability which apply to all Pi Innovo products and services.

OpenECU developer software has been tested to work with Windows 10. OpenECU is compatible with Windows 7 SP1 (32-bit and 64-bit) and Windows XP SP3, but support for these operating systems is deprecated. OpenECU is not compatible with Windows Vista or Windows 8.

For C based development, OpenECU requires (at a minimum) one of the following compiler tools:

To program and calibrate an OpenECU with an application, OpenECU integrates with the following calibration tools. Only one calibration tool is required:

For Simulink model based development, OpenECU requires (at a minimum) the following MathWorks tools:

In addition, if you need to add state diagrams to the model, then you will also need:

Simulink Coder generates C code which does not lend itself to efficient repeatable testing. When creating a production version of your product, you may need better control of the structure of the C code generated from the model to reduce the cost of testing the C code against any industry standards. Under these circumstances you will also need:

To compile the generated C code (from either Simulink Coder or Embedded Coder), you will need one of the following compilers:

To program and calibrate an OpenECU with an application, OpenECU integrates with the following calibration tools. Only one calibration tool is required:

OpenECU works with a number of applications (both required and optional) supplied by other companies. If you intend to use OpenECU with one of the following tools, it is best to install them before OpenECU. The installer will then integrate the OpenECU developer software with these applications.

OpenECU works with a number of other applications, but these need not be installed prior to the OpenECU developer software.

The applications above have been listed with a version or release number. These are the versions or releases that OpenECU has been tested against. It may be that OpenECU will work with other versions of these applications, but it is recommended against and Pi may not provide technical support if these versions or releases are not used.

In summary, the following third party tools are compatible with this version of OpenECU:

Some third party tools have been marked deprecated and support for these tools will be removed in a future release of OpenECU.

To setup a floating license, the vender daemon will have to be run on the designated license server as well as have a license file on that machine. This section describes setting up the vendor daemon for a floating license.

To setup a node-locked license, a license file must be placed on the development machine.

GCC, also known as the GNU Compiler Collection, is a free compiler system produced by the GNU Project supporting various programming languages. The Free Software Foundation (FSF) distributes GCC under the GNU Public License (GNU GPL). GCC has been adopted as the standard compiler by most modern Unix-like computer operating system and has also been ported to a wide variety of processor architectures and is available for most embedded platforms.

GCC is used with permission under the GPL Version 3. If GCC is installed with OpenECU, the license file can be found in the [install path]\tools\gcc\ppc\docs directory of the OpenECU install. If desired, a copy of the GCC source code can be found and downloaded from the Pi Innovo website.

Support for GCC is currently in beta and as such, the user may run into issues which can cause an application to fail to build or run correctly on target. Listed below are a set of known issues when building an application using GCC. See Appendix K, Contact information for details on how to get in contact with OpenECU support if support is needed for using GCC.

GCC is not recommended for production programs at this time.

Python is general purpose, high level interpreted programming language, distributed under the PSF license which allows use in non open-source commercial applications. The license can be found in the [install path]\tools\python\license.txt file.

Before any engineering project reaches the design and modelling stage, several detailed planning stages should be carried out to define suitable functional requirements and specifications. Once you have a detailed target for your design, you can then start to create and model it. Many engineers prefer to use pen and paper, but it's equally acceptable these days to develop your design directly in modelling packages such as MATLAB and Simulink.

In this example, we have designed and partially modelled the system for you — you need only finish the modelling process as described below.

While designing and running the model, and later testing it with the calibration tool, it is very useful to be able to interactively display and set the values that are present on parts of the model. You can do this by assigning names to a signal or input at the modelling stage, and then display or set the value associated with that variable as the model simulation is running.

Variables must be named according to a system described in full in Section 5.2.5, “Naming rules”. This system helps you to identify what type of information the variable holds, and where it is initialised and used — very helpful in tracking down any design faults. Note that calibratable variables of this type can only be changed on-the-fly with the development ECU (i.e. not with the fleet ECU, which requires programming of its memory to change any variable values).

3.3.2.1. Signals

We will use two signal variables in our design:

stp_ect

This is the value of the temperature that is output from the Analogue Input block, representing the temperature of the engine in degrees Centigrade;

stp_ect_state

This is the result of the relational operator that calculates whether the engine temperature is greater than the threshold temperature. It is 1 when the threshold is breached, and 0 otherwise.

Label the signals on either side of the Relational Operator block as follows:

To assign a name to a signal:

1. double-click on the appropriate signal and a text box will open beneath it;

2. type in the variable name, then click outside the box to complete.

Before we can run the model simulation, each Simulink block requires a number of parameters that define initial conditions, sample rates, and various other dynamic properties of the model.

Block parameters are set by double-clicking on the block and entering appropriate values in the various parameter fields that are displayed. Some parameters may only take on certain values, in which case the text field is replaced by a drop-down list, from which you can select the appropriate value.

3.3.3.1. Setting the model identification parameters

The parameters dialogue box for the Model Identification looks like this:

Set the block mask parameters as the figure shows. A full description of the block mask parameters is given later on Section 6.1.63, “Model identification (put_Identification)”, but a summary of the items and their meaning is given here for this example.

Table 3.1. Step1 - model identification block parameters

Parameter	Description	Set to
ECU type	Identifies the name of the type of ECU.	(already set by running the oe_create_model command)
Part Number	Identifies the hardware part number of the ECU.	(already set by running the oe_create_model command)
Issue number	Identifies the issue number of the ECU.	(already set by running the oe_create_model command)
Pin naming	Specifies the naming given to each blocks channel or pin selection.	Generic pin naming
Application name	Specifies a name for the application/model. Although this parameter has no functional effect on the model, it is used when generating the model ASAP2 file and can be retrieved over CCP using the EXCHANGE-ID message.	Step1 example, v%ver-major%.%ver-minor%.%ver-subminor%, %target%
Description	Specifies a description of the model (this parameter has no functional effect on the model).	Step1 model from OpenECU manual.
Major version number	Specifies the major version number of the model. This value can be read over CCP by a ASAP2 compliant tool and is useful to determine if the target hardware is running the correct version of the model.	1
Minor version number	Specifies the minor version number of the model. This value can be read over CCP by a ASAP2 compliant tool and is useful to determine if the target hardware is running the correct version of the model.	0
Sub-minor version number	Specifies the minor version number of the model. This value can be read over CCP by a ASAP2 compliant tool and is useful to determine if the target hardware is running the correct version of the model.	0
Copyright	Specifies a copyright for the model (this parameter has no functional effect on the model).	2012.

Note

It is essential to include a put_Identification block in all OpenECU top level models. If this block is not present, the model will not work as documented.

3.3.3.2. Setting the CAN configuration parameters

The parameters dialogue box for the CAN Configuration looks like this:

Set the block mask parameters as the figure shows. A full description of the block mask parameters is given later in Section 6.1.13, “CAN configuration (pcx_CANConfiguration)”, but a summary of the items and their meaning is given here for this example.

Table 3.2. Step1 - CAN configuration block parameters

Parameter	Description	Set to
Bit rate	The bit rate (or baud rate) of the CAN bus.	500 kBps
CAN bus identifier	Which CAN bus the configuration applies to.	CAN 0

3.3.3.3. Setting the CCP Configuration parameters

The parameters dialogue box for the CCP Configuration looks like this:

Set the block mask parameters as the figure shows. A full description of the block mask parameters is given later in Section 6.1.19, “CCP configuration (pcp_CCPConfiguration)”, but a summary of the items and their meaning is given here for this example.

Table 3.3. Step1 - CCP configuration block parameters

Parameter	Description	Set to
Receive message identifier	A unique standard CAN message identifier for CCP CRO messages. This is the CAN identifier used to talk to the OpenECU device. For this example, we'll use the default value.	1785
Transmit message identifier	A unique standard CAN message identifier for CCP DTO messages. This is the CAN identifier used to talk from the OpenECU device. For this example, we'll use the default value.	1784
Station address	The station address for CCP sessions. OpenECU will only communicate using CCP if a session is opened using this station address. For this example, we'll use the default value.	0
CAN bus identifier	Which CAN bus CCP communications will occur on. Previously, we configured CAN 0 to run at 500 kBps, so we'll use CAN 0 for CCP communications.	CAN 0
Enable CCP during model execution?	Whether to communicate using CCP when the model is executing or whether it will only communicate using CCP when programming. We will want to view signals stp_ect and stp_ect_state when the model is running (and possibly change calibrations as well) so this should be ticked.	(tick)
Use CRO extended ID? (29 bit)	As the model has been configured with 11 bit CAN identifiers for CCP i.e., CRO set to 1785, so this should be unticked.	(untick)
Use DTO extended ID? (29 bit)	As the model has been configured with 11 bit CAN identifiers for CCP i.e., DTO set to 1784, so this should be unticked.	(untick)

3.3.3.4. Setting Analogue Input parameters

The parameters dialogue box for the Analogue Input looks like this:

Set the block mask parameters as the figure shows. A full description of the block mask parameters is given later on Section 6.1.6, “Analogue input — processed (pai_AnalogInput)”, but a summary of the items and their meaning is given here for this example.

Table 3.4. Step1 - analogue input block parameters

Parameter	Description	Set to
Channel	Which channel will be used for the raw input from the temperature sensor.	AIN (pin A19) for M220, AIN (pin A19) for M250, AIN (pin A28) for M460 and M461, or AIN (pin Y31) for M670
Raw data units	Units in which the raw analogue values for this block are interpreted.	Volts
Transfer function type	The type of tranfer function to use when converting from raw values to engineering values. In this example we set it to use an interpolating lookup map.	Map
Transfer function raw axis	The values of this and the engineering lookup define a transfer function that is characteristic of the particular temperature sensor we're using. The raw axis defines some arbitrary inputs to the sensor, and the eng lookup defines the corresponding output behaviour. Note that the number here represents the analogue pin voltage because Raw data units is set to Volts.	[.2 1.12 2.04 2.96 3.88 4.8]
Transfer function engineering lookup	(see above)	[135 96 74 55 20 -42]
Default engineering value	The default starting value for the parameter (in °C).	60
Separate min/max values	Option to separate the Minimum/maximum engineering value and Minimum/maximum raw value into four separate parameters. Not used in this example.	unchecked
Minimum/maximum engineering value	The minimum and maximum values that are to be expected for this value (in °C).	[-40 130]
Minimum/maximum raw value	The minimum and maximum raw values that are expected at the input to the block's transfer function. These units correspond to the setting of Raw data units, hence the range for Volts.	[0 5]
Absolute raw slew rate limit	The maximum rate at which the signal is expected to rise or fall. By setting this to a large number, we can ensure that the block will never detect a slew rate limit fault.	10000000
Leaky bucket rise rate	This is the threshold rate above which incoming fault data will trigger a permanent fault. Setup for this example so that a fault is never detected.	20
Leaky bucket fall rate	This is the threshold rate below which incoming fault data will cease to trigger a fault indication. Setup for this example so that a fault is never detected.	10
Leaky bucket hysteresis	This is the amount of hysteresis in the leaky bucket fault filter system. Setup for this example so that a fault is never detected.	0.5
Sample time	The time (in seconds) between samples, i.e., how often this block will be integrated.	0.01

The transfer function allows for non-linear conversion but must adhere to the same restrictions as the put_Calmap1d block (e.g., regarding axis monotonicity). The transfer function from the analogue input block data above in Figure 3.4, “Analogue input transfer function”.

Figure 3.4. Analogue input transfer function

3.3.3.5. Setting PWM Output parameters

The parameters dialogue box for the PWM Output looks like this:

Set the block mask parameters as the figure shows. A full description of the block mask parameters is given later on Section 6.1.84, “PWM output — fixed frequency (pdx_PWMOutput)”, but a summary of the items and their meaning is given here for this example.

Table 3.5. Step1 - PWM output block parameters

Parameter	Description	Set to
Channel	Which channel will be used for the PWM output signal.	DOT (pin A37) for M220, DOT (pin A18) for M250, DOT (pin A15) for M460 and M461, or DOT (pin Y29) for M670
Inversion	Whether the logical function of the block will be inverted (ticked) or not (unticked).	(unticked)
Default duty cycle	The default output duty cycle used when a fault is specified. In this example, the fault inport is always force to zero, so this condition never arises.	1
Initial duty cycle	The initial duty cycle before the model starts to run.
Frequency	The frequency of the signal. Although this example always uses a 0% or 100% duty cycle, i.e., always on or off, the frequency must still be specified.	1000
Offset	The offset of the signal relative to other PWM signals of the same frequency. An advanced feature that can be ignored in this case.	0
Minimum/maximum duty cycle	The minimum and maximum duty cycle range for this input.	[0 1]
Sample time	The time (in seconds) between block iterations.	0.01

This example uses a PWM output to drive an output either fully on (100% duty-cycle) or fully off (0% duty-cycle). A digital output block Section 6.1.43, “Digital output (pdx_DigitalOutput)” could have been used instead and is the more logical choice for this example. However, the example uses a PWM output block to show that different outputs can be used in equivalent ways.

3.3.3.6. Summary so far

Your model should now look like Figure 3.5, “Configured quick start model”.

Figure 3.5. Configured quick start model

So far, you have populated the model with a number of Simulink and OpenECU blocks, defined some behaviour by linking the blocks together to interact and now need to provide the framework around the model to allow it to be built and run on an OpenECU device.

Your model file includes the information to describe the dynamics of your design, but it needs some other information — parameters and initial values of variables — to function correctly and remain flexible for future alterations and additions to its design. There are two types files that are used for this:

Draft versions of these resource files were created by the oe_create_model command.

The model is now complete, but before its built, we can check it by updating the model. This also activates a number of visual indicators which help the user read the model, including library links and rate colouring.

To update the model (right click on the background and select the Update diagram menu item). Your model should now look like Figure 3.6, “Updated quick start model”.

Figure 3.6. Updated quick start model

To run your model in simulation prior to running it on OpenECU target hardware select Start from the Simulation menu, or click on the button in the Simulink toolbar. If your model has no design errors in it, and Simulink can find all the resources it needs, the simulation will run.

Of course, for this example, you cannot change the behaviour of the simulation as it runs. In order to do this, you can replace the ground input to the pai_AnalogInput block with a signal generator and attach scopes to the signals to view during the simulation.

The process of building the model creates a number of files which can be downloaded or programmed into an OpenECU to run in real-time. The build process is started by selecting the model, and either pressing CTRL-B or selecting the menu option Tools -> Real-Time Workshop -> Build Model. This instructs RTW to generate C code from the model and to invoke OpenECU's template makefile to compile the C code.

The result of a successful build produces a number of files in the same directory as the step1 model:

If the build fails for any reason, go back through the stages of the example and identify any corrections, or look at the installed and completed step1 model to identify any differences.

The OpenECU is programmed with any CCP compliant tool. Specific instructions for ATI Vision, Vector CANape and ETAS INCA calibration tools are provided in Appendix B, Supporting tools.

At a minimum, the OpenECU device will need to be powered and be connected to the CCP tool over CAN as shown in the following diagram.

The OpenECU device can be programmed by following these steps:

Once programmed, ground the FEPS pin, power cycle the ECU, and the application will start. Then use an ASAP2/CCP compliant tool to view the stp_ect and stp_ect_state signals, and to set stpc_ect_limit (if you are using a developer module).

During the installation of OpenECU, menu items are added to Windows Start menu. You can access OpenECU documentation by selecting the Start menu, then OpenECU Developer Software, then the version of OpenECU that is of interest:

Figure 4.1. OpenECU integrated with Window's Start button

Having asked for MATLAB integration during the installation of OpenECU developer software, the OpenECU blockset is available to use from within Simulink. The integration with MATLAB resembles other blocksets, and as closely as possible, OpenECU tries to integrate into the existing available MATLAB commands.

To find out if OpenECU was successfully installed, type the following command at the MATLAB prompt:

ver openecu

and MATLAB will display the version of OpenECU installed. A correct response will look something like:

OpenECU Blockset (Pi Innovo)             Version 2.9.0 (r2020-1)

In MATLAB R2013a through R2015b, the user guide can be reached by selecting Help > Documentation from the main toolbar, then by selecting Supplemental Software on the window that appears. Finally select OpenECU (Pi Innovo) Blockset which is listed in the contents of the Supplemental Software window.

Figure 4.2. OpenECU integrated with MATLAB's help system (R2015a - R2015b)

In MATLAB R2016a and later, the user guide can be reached by selecting Help > Documentation from the main toolbar, then by selecting OpenECU (Pi Innovo) Blockset.

Figure 4.3. OpenECU integrated with MATLAB's help system (R2016a - R2020a)

The blockset is accessible through the library browser, which is itself available through any main Simulink window:

Figure 4.4. OpenECU integrated with MATLAB's library browser (R2015a - R2020a)

The functionality of OpenECU is split into various components (e.g., angular, input, output) and documented in Section 4.6, “OpenECU blockset features”. The blocks can be dragged from the library browser to a model.

The OpenECU blockset is integrated into MATLAB through various standard commands:

Further commands specific to OpenECU are available and reference documentation is available in Section 6.4, “OpenECU commands”.

To help explain the methods for working with OpenECU, Figure 4.5, “Example development pattern for modelling an application” shows a simple development process for working with a model and an ECU.

Figure 4.5. Example development pattern for modelling an application

An OpenECU model consists of three or four components:

4.2.2.2. Data dictionary files

A data dictionary can be either a text file, or a Simulink proprietary format file with the extension .sldd starting in R2015a. Prior to R2015a only text file based data dictionary files are supported.

4.2.2.2.1. Text file based

A text file based data dictionary file is a simple tab delimited text file format and must contain at minimum: the name, default value and type for calibratables and the name and type only for displayables. When a model is loaded, the data dictionary files are read into MATLAB's workspace to support simulation or building. Optionally, these can be used to generate ASAP2 files at build time. See Section 4.3.4, “Configuration options” for details.

Note that non-ASCII characters appearing in the data dictionary may not be interpreted correctly by the calibration tool reading the resultant ASAP2 files, since different calibration tools use different extended encoding conventions. It is best therefore to stick to ASCII characters within the data dictionary.

Each data dictionary file is stored in a directory of the same name. Given the example of the model read_sensor above, then there would be two directories named min and mot:

Each data dictionary file stored in each of those directories must be named data dictionary name_dd.txt. Given the example of the model read_sensor above, then there would be two files named min_dd.txt and mot_dd.txt in the corresponding directories:

Each data dictionary follows a simple format, separated into columns and will look something like:

Name            Value  Units  Type    Accuracy  Min  Max  Description
moi_pressure           kPa    real_T  0.01      20   80   Pressure reading
moi_temperature        degC   real_T  0.01      -40  150  Temperature reading

To help readability, comment lines can be inserted into a data dictionary file. Comment lines are ignored and start with either a ** or the -- character sequence. For example:

Name            Value  Units  Type    Accuracy  Min  Max  Description
** A comment line
moi_pressure           kPa    real_T  0.01      20   80   Pressure reading

-- Another comment line
moi_temperature        degC   real_T  0.01      -40  150  Temperature reading

Each column has a heading, followed by as many data dictionary entries as necessary. Each column is separated by a TAB character and because of this, Excel is a very useful tool for editing the files (in Excel, save the file as Text (tab delimited) *.txt).

Each column has a use:

Table 4.2. Data dictionary columns

Column	Description
Name	The name of the data dictionary entry. The name must conform to the naming convention detailed in Section 5.2.5, “Naming rules”.
Value	The value of a calibration constant, 1d or 2d map. A value should not be created for a Simulink signal.
Units	The engineering units for this entry (can be restricted to a set of possibilities with a units file (Section 4.2.2.3, “Units file”)).
Description	A description of the data dictionary entry. Must not contain single or double quotes.
Type	Any one of int8_T, uint8_T, int16_T, uint16_T, int32_T uint32_T, real_T or bool. The type must match the type assigned to the signal by Simulink.
Accuracy	The number of decimal digits to display when viewing the data dictionary entry with a calibration tool. For instance, 1 shows no digits after the decimal point, 0.01 shows two digits after the decimal point.
Min	The minimum expected value for this data dictionary entry.
Max	The maximum expected value for this data dictionary entry.
Scale	This column is optional. It specifies the amount by which the displayed value will be scaled from the raw value read from the ECU.
Offset	This column is optional. It specifies the amount by which the displayed value will be offset from the raw value read from the ECU.
Enums	A comma separated list of data dictionary entries which provide the possible values this data dictionary entry can be. This column is optional.
Defn	This column is optional. It specifies the file in which the equivalent C variable for the DDE will be defined. Only applicable when using RTW Embedded Coder, the column is ignored for other auto-coders.
Decl	This column is optional. It specifies the file in which the equivalent C variable for the DDE will be declared. Only applicable when using RTW Embedded Coder, the column is ignored for other auto-coders.
Lookup	Reserved for future use, do not use.
Group	Reserved for future use, do not use.
Rate	Reserved for future use, do not use.

An example of how the data dictionary can be used to name model signals, model constants and map look-ups is given below. Each entry follows the naming convention laid out in (Section 5.2.5, “Naming rules”). Explore the OpenECU demos for more examples (Section 3.2, “Installed examples”).

Name           Value               Units  Type    Min Max  Description

** Example of a signal DDE
moi_pressure                       kPa    real_T  20  80   Example of a named signal

** Example of a constant look-up DDE
moic_constant  50                  kPa    real_T  20  80   Example of a calibration constant

** Example of set of a 1D table/map look-up DDEs
moim_1d_map_x  [20 40 80]          kPa    real_T  20  80   Example of a x-axis for a 1d map
moim_1d_map_z  [0  0  1]           state  bool    0   1    Example of a z-data for a 1d map

** Example of set of a 2D table/map look-up DDEs
moim_2d_map_x  [20 40]             kPa    real_T  20  80   Example of a x-axis for a 2d map
moim_2d_map_y  [1  5  10]          sec    real_T  0   25   Example of a y-axis for a 2d map
moim_2d_map_z  [0  1; 4  5; 8  9]  steps  real_T  0   100  Example of a z-data for a 2d map

** Example of set of an array DDE
moiv           [1 2 3 5 8 13]      counts real_T  0   100  Example of an array

Instead of using values to represent discrete states, enumerations can be used instead. These represent the discrete states using a textual name rather than a number. For instance, in the following example, moi_state can have two enumerations: MOI_RUNNING which represents the value 0 and MOI_STOPPED which represents the value 1. It is easier to understand and interpret the enumerations than the values.

Name         Value  Units  Type    Min  Max  Enums                     Description

moi_state           state  real_T  0    1    MOI_RUNNING, MOI_STOPPED  Example of a st ...

MOI_RUNNING  0      enum   real_T                                      Enumeration for ...
MOI_STOPPED  1      enum   real_T                                      Enumeration for ...

When a model is loaded, each data dictionary entry is checked for errors. A complete list of checks is given in Appendix H, Data dictionary tool errors. If any errors or warnings are displayed, go back and edit the file to remove the errors.

Note

When a data dictionary is changed OpenECU does not automatically read the file. Instead, the user must read the data dictionaries by running the command:

oe_read_build_list

at MATLAB's prompt.

4.2.2.2.2. Simulink based

In R2015a and later, a Simulink based data dictionary file with an extension of .sldd can be used with OpenECU. This type of data dictionary holds the same information as a text based data dictionary, only the data is stored in oe.Parameter and oe.Signal objects in the data dictionary file from within Simulink, instead of externally in text files. This file can be edited manually from within Simulink using the Model Explorer interface, or programmatically in Simulink using the Simulink.data.dictionary class and API.

The data dictionary file is specified in the Model Properties dialog box of the model File-> Model Properties-> Model Properties under the Data tab, as shown in the image below.

The data dictionary file can be viewed or edited by clicking the icon in the bottom left hand corner of the model once it has been configured to use a data dictionary, as shown below.

The data dictionary file is then edited in Model Explorer Tools-> Model Explorer, as shown below.

To add a new oe.Parameter or oe.Signal object to the data dictionary select Add-> Add Custom... from the Model Explorer menu, and in the dialog box, specify the name of the variable and the class of the variable (either oe.Parameter or oe.Signal), as shown below.

OpenECU uses the following properties for each signal object:

Table 4.3. Simulink data dictionary object properties

oe.Parameter property	oe.Signal property	Text based column equivalent	Description
Object name	Object name	Name	The name of the object in the data dictionary. The name does not need to conform to the naming convention if the model is configured to use oe objects, and to disable the naming convention.
name.Value		Value	The value of a paramter constant, 1d or 2d map. Only valid for oe.Parameter objects.
name.DocUnits	name.DocUnits	Units	The engineering units for this entry. Units file is not supported.
name.Description	name.Description	Description	A description of the data dictionary entry.
name.DataType	name.DataType	Type	A Simulink supported data type.
name.Accuracy	name.Accuracy	Accuracy	The number of decimal digits to display when viewing the data dictionary entry with a calibration tool. For instance, 1 shows no digits after the decimal point, 0.01 shows two digits after the decimal point.
name.Scale	name.Scale	Scale	The amount by which the displayed value will be scaled from the raw value read from the ECU.
name.Offset	name.Offset	Offset	The amount by which the displayed value will be offset from the raw value read from the ECU.
name.Min	name.Min	Min	The minimum expected value for this data dictionary entry.
name.Max	name.Max	Max	The maximum expected value for this data dictionary entry.
name.Enums	name.Enums	Enums	A comma separated list of oe.Parameter objects which provide the possible values this data dictionary entry can be. This property can be left blank.
name .CoderInfo .CustomAttributes .DefinitionFile	name .CoderInfo .CustomAttributes .DefinitionFile	Defn	This property is optional. It specifies the file in which the equivalent C variable for the DDE will be defined. Only applicable when using Embedded Coder, the property is ignored for other auto-coders.
name .CoderInfo .CustomAttributes .HeaderFile	name .CoderInfo .CustomAttributes .HeaderFile	Decl	This property is optional. It specifies the file in which the equivalent C variable for the DDE will be declared. Only applicable when using Embedded Coder, the property is ignored for other auto-coders.

With a Simulink data dictionary, in order to make each variable available in a calibration tool, the variable must have certain properties set in order to control the storage of that variable. The properties must be set differently depending on the auto-coder used (see Section 4.3.2, “Auto-coders” for more details about auto-coders), and the desired type and scope of the variable.

The following table details the desired variable type in the model or calibration tool, and the data object and properties required for each auto-coder which must be set to generate that variable in the model and make available in the calibration tool:

Table 4.4. Simulink data dictionary object storage classes

Variable type	Auto coder	Data object	Properties
Constant scalars	any	oe.Parameter	name .CoderInfo .StorageClass = 'Auto'
Calibration scalars Calibration maps (1d or 2d), or Arrays	GRT RTMODEL	oe.Parameter	name .CoderInfo .StorageClass = 'ExportedGlobal'
Displayable signals	GRT RTMODEL	oe.Signal	name .CoderInfo .StorageClass = 'ExportedGlobal'
Calibration scalars Calibration maps (1d or 2d), or Arrays	EC	oe.Parameter	name .CoderInfo .StorageClass = 'Custom' name .CoderInfo .CustomStorageClass = 'Global' name .CoderInfo .CustomAttributes .MemorySection = 'Calibration'
Displayable signals	EC	oe.Signal	name .CoderInfo .StorageClass = 'Custom' name .CoderInfo .CustomStorageClass = 'Global' name .CoderInfo .CustomAttributes .MemorySection = 'Displayable'

Note

In the Model Explorer interface, the name.CoderInfo.StorageClass, and name.CoderInfo.CustomStorageClass, properties are normally merged into the same drop down selection field. The 'Global (Custom)' selection will select both name.CoderInfo.StorageClass = 'Custom' and name.CoderInfo.CustomStorageClass = 'Global' at the same time.

Note

The oe.Signal and oe.Parameter object classes are derived from the native Simulink.Signal and Simulink.Parameter classes and are designed to better integrate with OpenECU projects. It is highly recommended to use the OpenECU specific object whenever possible, as the Simulink native object classes are not officially supported by OpenECU.

A model configured to use a text based data dictionary can be automatically converted to use a Simulink data dictionary with all of the existing data dictionary entries imported into the .sldd file by calling the following command:

oe_config_using_sim_dd

at MATLAB's command prompt.

By default, the script will convert the currently active model, using the data dictionary file name model-name.sldd. If the data dictionary file already exists it can be overwritten with additional parameters. See details at oe_config_using_sim_dd.

In addition to the previously mentioned data dictionary variables, additional data can also be stored in a Simulink data dictionary file, such as Simulink.Bus objects, Simulink enum type definitions, Configuration Sets, and other built-in Simulink types. Please refer to the Simulink documentation for further details on the data that can be stored in a Simulink data dictionary file.

degC
kPa

** Allowable units for the read_sensor model
degC
kPa

feature_list = [{'min',
                 'mot'}];

The update model stage adds or adjusts the functionality of the model. It's important to keep the data dictionary files up to date with changes to the model. It's easy to leave changes to the data dictionary until later, but that often leads to multiple build and update cycles as missing data dictionary elements are found during the testing stage.

Before Simulink starts to simulate a model on the host PC, or builds a model to run on an ECU, Simulink attempts to solve the model and applies consistency checks during the solving. This process is called a diagram update. A diagram update can be performed at any point by pressing CTRL+D in a model window, or by selecting the Edit -> Update diagram.

4.2.3.1. Model composition

If you are unfamiliar with Simulink models then note that it is worth the extra effort up front to partition your application into smaller blocks of functionality. Each block of functionality is placed in a subsystem. With complex areas of functionality, breaking those areas of functionality into less complex interrelated blocks, each within a subsystem, can help readability.

Simulink provides a Model Explorer tool which makes it easy to navigate between parts of the model based on the hierarchy of the subsystems. And OpenECU can incorporate the model hierarchy into the files used to communicate with the ECU while the ECU is running the model.

For instance, at a top level, a useful pattern to follow breaks the model into an input, output and application subsystem.

Figure 4.6. Breaking the input and output processing from the application

Input processing

The input subsystem reads sensor and actuator feedback signals and decodes communication messages, transforming raw sensor information into engineering units (possibly applying filters and other validation techniques to ensure the input data is usable). The input subsystem can be broken down into further subsystems, perhaps one to read the raw sensor information, one to process into engineering units, and one to validate the inputs (perhaps against other sensor inputs or against a plant model of the system under control).

Application processing

The model subsystem processes the input subsystem data, determining how the system it is controlling should react. The model subsystem would be further broken down into smaller subsystems, each performing a small portion of the overall functionality. The model subsystem creates the data in engineering units necessary to drive the output subsystem.

Output processing

The output subsystem drives the actuators connected to the ECU to achieve the demands of the model subsystem.

By breaking the model into these subsystems, the input and output subsystems can easily be replaced when targeting another ECU. For instance, when moving to a more powerful ECU because the application has grown, or when moving to a less powerful ECU because the production needs for the prototyped application mean a cheaper ECU can be used.

Simulink provides a mechanism to simulate the model on the host PC. Please refer to the Simulink documentation for further details. Note that while simulation has many uses, it is not necessary to simulate the model before building the model to run on an ECU.

With the application model and data dictionary files in place, the application model can be built and linked with the OpenECU and compiler libraries to generate a binary image which can be programmed and run on an OpenECU.

To start a build, press CTRL+B in a model window, or select the menu option Tools -> Real-Time Workshop -> Build model.

Detail on the build process, the generated build files and a summary of common issues can be found in Section 4.3.6, “Building a model”.

The OpenECU is programmed with any CCP compliant tool. Specific instructions for ATI Vision, Vector CANape and ETAS INCA calibration tools are provided in Appendix B, Supporting tools.

At a minimum, the OpenECU device will need to be powered and be connected to the CCP tool over CAN as shown in the following diagram.

The OpenECU device can be programmed by following these steps:

Once the ECU has been programmed, the ECU remains in reprogramming mode until the ECU is restarted by power cycling the ECU. Without FEPS applied, the ECU will enter application mode and run the model.

The testing phase seeks to ensure that the built Simulink model acts as expected under all circumstances. OpenECU provides a CCP interface to allow calibration tools to access model information. See Appendix B, Supporting tools for an introduction to how to use one of the supported calibration tools to monitor the model while it runs on the ECU.

While OpenECU works with most of the functionality of Simulink and RTW, there are only a few major restrictions when using the OpenECU blockset in conjunction with RTW. Those that must be avoided are discussed in more detail below.

Simulink Coder (formerly Real-Time Workshop) provides a number of different auto-coders, each with increasing levels of functionality:

See OpenECU Compatibility with Third Party Tools for a complete list of supported coder versions.

OpenECU provides a collection of configuration sets to select between each of these auto-coders.

A configuration set comprises groups of related parameters called components. These components provide various options which control how an auto-coder generates code from a model. Configuration sets can be viewed through Simulink's Model Explorer.

Figure 4.7. Simulink's Model Explorer showing OpenECU configuration sets

The picture in Figure 4.7, “Simulink's Model Explorer showing OpenECU configuration sets” shows an OpenECU configuration set for each of the auto-coders described in Section 4.3.2, “Auto-coders”. Only one configuration set is used at any time and Simulink shows this by marking it active (in this case, the GRT RTMODEL auto-coder is active).

Each of the components is listed in the middle pane. Selecting any of the components shows the component options in the right hand pane. Although it is possible to modify these options, it is recommended that models keep the original OpenECU settings.

OpenECU provides a number of configuration options which affect the build process. The options can be accessed by opening an OpenECU model and selecting the menu option Simulation-> Configuration Parameters... (or Simulation-> Model Configuration Parameters in later versions of Simulink) then browsing to the OpenECU options under Real-Time Workshop (or Code Generation in later versions of Simulink).

Under the Real-Time Workshop (or Code Generation in later versions of Simulink) categories, there are both built-in Simulink options, and OpenECU additional options.

The built-in Simulink options that OpenECU recognizes are:

The OpenECU additional options are grouped into the following categories:

Switching between configuration sets changes the RTW auto-coder. This can be done one of two ways: right click on the configuration set in Simulink's Model Explorer and select Activate; or place one (or more) of the prtw_ConfigUsingRtwEc, prtw_ConfigUsingRtwRtmodel helper blocks in the model and double click the appropriate one.

The helper blocks perform a couple of actions which the Model Explorer won't.

As outlined in Section 4.2.5, “Build model”, a model build creates the target ECU images which can be programmed onto an ECU and run in real-time. Figure 4.8, “Building an application (in outline)” gives an outline of the build process.

Figure 4.8. Building an application (in outline)

The build process has a number of inputs:

The inputs are processed in a number of steps to create intermediate objects:

From those intermediate steps, the final set of objects are created:

To build the executable code for the ECU, select the model window so it becomes focused then press CTRL+B to start the RTW build. Alternatively, place a prtw_Build block in the model and double click the block.

The build process starts by re-reading the build list to ensure the latest DDE information is present when generating the ASAP2 file.

### Starting Real-Time Workshop build procedure (with modification for OpenECU) for model:
Clearing any previously loaded build list...
Obtaining workspace data from each feature data dictionary...
Workspace variables loaded

The build then continues with the standard RTW build mechanism with a few additions for OpenECU. In some earlier versions of RTW, if this is the first time the model has been built, the build creates the RTW library which can take some minutes to complete. Subsequent builds of the same model skip this part of the build.

4.3.6.1. Build output

During the build, MATLAB will display a series of diagnostic and status messages with respect to the build. In MATLAB versions prior to r2014b, all messages will be logged to the main MATLAB console.

In MATLAB versions r2014b and later messages will be logged to The Diagnostic viewer window. This window can be viewed by clicking the link at the bottom of the model window.

Strategy memory:
 142696 bytes of strategy/code memory used
 250519 bytes remaining
Calibration memory:
   3376 bytes of calibration memory used (rough indication, includes Simulink support data)
 258767 bytes remaining
Workspace memory:
  14040 bytes of workspace/displayable memory used, including
    176 bytes of adaptive data, and
      2 bytes of diagnostic trouble code data, and
   8192 bytes of model stack
  24008 bytes remaining
Built at: 2005, 08, 02 (year, month, day) 10:52:47 (hour:min:sec)

When the ECU is turned on (or is recovering from a powered reset), the bootloader performs various tests. These include:

If the tests fail then the bootloader will either reset or attempt to enter reprogramming mode, flashing a code to indicate the cause (see the technical specification for each ECU for details about code flashing). If the tests pass, then the bootloader will determine what mode to enter next (see Section 4.4.2, “Reprogramming mode” and Section 4.4.3, “Application mode” for details on how each mode is chosen).

When the ECU is turned on (or is recovering from a powered reset), the bootloader will enter reprogramming mode if the FEPS pin is asserted, if there is an invalid application image in memory, or for certain targets if the ECU is running the application and allowing reprogramming while a reprogramming request is received (FEPS-less).

In reprogramming mode, the ECU listens to the communications buses for instructions to reprogram, as described in Section 4.5, “Programming an ECU”.

When the ECU is turned on (or is recovering from a powered reset), the bootloader will enter application mode if the FEPS pin is not asserted and if there is a valid application image in memory.

When application mode is entered, the library initialises the ECU hardware and starts running the application model.

The platform performs various operations in the background including checks on RAM hardware. If a RAM error is detected, an unrecoverable error is raised (resulting in ECU reset) because program execution is otherwise likely to fail in an unpredictable manner.

Similarly non-volatile data is revalidated in the background and treated as if it is no longer available if validation fails. Thus if run-time memory corruption occurs affecting non-volatile data, any subsequent attempt to read that data will be handled in the same way as if the data were not present (default used instead).

Background checking for code or calibration corruption works through the Calibration Verification Number computation on supported targets with the OBD library option. Ensure that the CVN is recomputed continually if run-time corruption checking is required. If it is detected, an unrecoverable error is raised (resulting in ECU reset). This is in addition to boot-time checksum validation.

Calibratables and displayables are defined in a data dictionary, which can be set up per model. More details are given in Section 4.2.2.2, “Data dictionary files”.

OpenECU has specific support for ATI Vision, ETAS INCA and VECTOR CANape but can also generate generic ASAP2 information for inclusion into any ASAP2 compliant calibration tool.

The blockset library provides a series of blocks which allow the modeller to adjust scalars, 1-d and 2-d maps while the model is being iterated.

The blockset library provides access to non-volatile storage: storage retained when the power is removed from the module by either connecting a low power source to the Keep alive power pin to retain the contents of RAM storage, or by committing the data to Flash storage (see the technical specification for details on which storage type is supported by each target).

Although not necessary in the majority of cases, it is sometimes useful to be able to modify the compiler or linker options while building a model. For instance, to turn on debug symbols, to turn off an optimisation which may be causing a problem, or to affect preprocessor conditions of hand written code included in the build.

Sometimes, as the functionality of a block changes, the change cannot be made without breaking the behaviour the model expects of the block. For instance, when a block has a couple of options replaced by a single option, the block cannot adjust itself when the model loads, and Simulink will print a series of error messages.

When this kind of change occurs, rather than change the existing block, a new block is created with the new functionality, while the old block is retained as is. This allows the model to load without Simulink printing errors and the model can be changed to use the new block as required.

However, to remove old functionality over time, the old block will be removed in a future version of the developer software, ensuring the blockset remains efficient. Blocks which are to be removed in the future are marked deprecated, and the documentation for those blocks indicates how to replace the block with an equivalent block that isn't marked deprecated.

Currently, the following blocks are marked deprecated and will be removed in a future version of the developer software. Please replace the use these blocks as soon as possible.

The block library provides support for Diagnostic Trouble Codes (DTCs), or fault indicators, which can be organised into a series of tables.

and to provide simple signal checks:

The block library provides support for Parameter Identifiers (PIDs).

The block library provides support for freeze frames. Freeze frames capture pertinent operating conditions upon the occurrence of a fault. The platform supports freeze frames over the J1979 and J1939 protocols.

The block library provides support for service $09 InfoTypes.

The block library provides support for In-Use Performance Ratio (PPR).

The blockset library provides the mechanism for Simulink I/O blocks to access real hardware pins. There are a variety of general input blocks:

4.6.11.2. External devices

There are two types of I/O on OpenECU hardware: direct and indirect I/O.

Figure 4.12. Signal update rates

Direct I/O

Direct I/O takes place on demand. The application calls the necessary function and the function takes a measurement or sets a driver accordingly.

Indirect I/O

Indirect I/O is delayed.

For an input, the application calls the necessary function and the data to be read is taken from a buffer of data that was sampled some time ago. Once the model has completed each model rate once, the data is buffered at the quickest rate which requests the data. Thus indirect inputs are delayed by at most one iteration of the quickest rate which requests the input.

For an output, the application calls the necessary function and the data to be written is buffered and actioned some time later. Once the model has completed each model rate once, the buffered data is actioned at the quickest rate which writes the indirect output.

Indirect I/O always occurs when there is an device between the processor and the pin. The device communicates to the processor across a serial link and it is this communication which introduces the delay. Only I/O channels noted as serial in the technical specification (see Section A.1, “ECU hardware reference documentation”) are affected.

Wide band sensors (often referred to as UEGO sensors, for Universal Exhaust Gas Oxygen, or linear lambda oxygen sensor) generate an indication of the oxygen content in the exhaust gas mixture. Some modules provide UEGO inputs processed by Bosch CJ125 ASICs. The OpenECU platform provides an interface to control the CJ125 device:

UEGO sensors require careful control of the heating element to avoid damaging the ceramic heater, and careful control of the pump cell current to accurately measure the oxygen content. See the modules technical specification document for more details.

The blockset library provides the mechanism for Simulink I/O blocks to access real hardware pins. There are a variety of general output blocks:

as well as a way to control the overall status of the output drivers:

and a way to diagnose the status of the electrical connections of some ECU loads:

4.6.14.2. External devices

There are two types of I/O on OpenECU hardware: direct and indirect I/O.

Figure 4.13. Signal update rates

Direct I/O

Direct I/O takes place on demand. The application calls the necessary function and the function takes a measurement or sets a driver accordingly.

Indirect I/O

Indirect I/O is delayed. The application calls the necessary function but the data to be read or set is actioned some time after the function returns.

Indirect I/O always occurs when there is an device between the processor and the pin. The device communicates to the processor across a serial link and it is this communication which introduces the delay. Only I/O channels noted as serial in the technical specification (see Section A.1, “ECU hardware reference documentation”) are affected.

RTW creates software tasks for each rate in the model, and Simulink can colour each block in the model based on the rate of the block. This can make it easier to understand what parts of the model run at which rate, and to understand how information is passed between rates.

To support switching between auto-coders, the blockset library provides a set of blocks which switch between the different configuration sets. Simulink configuration sets contain options for a specific auto-coder. Currently, building models against the RTW (GRT RTMODEL) and RTW (EC) auto-coders is supported.

The blockset provides a utility block to start a model build. Pressing CTRL+B in a model window performs the same functionality.

All ECUs supported by OpenECU have a common subset of functionality, which applies equally to all ECUs.

Some ECUs have capabilities which don't fit into the standard framework, and special support is provided for those capabilities.

Real time applications, like those developed for OpenECU, often need to time events or durations, at different resolutions. The blockset library provides two mechanisms to manipulate time: using the Simulink task timers; and using the ECU processor's timers.

The I/O library also provides a number of support or utility functions to facilitate module configuration and diagnosis:

map look-up and interpolation:

signal conditioning:

For configuration management purposes, it can be useful to restrict the version of developer software that can be used when editing and building a model. The blockset library provides a flexible way to specify the allowable versions.

For configuration management and debugging purposes, it can be useful to know the versions of software running on an ECU are compatible. The blockset library provides a way to retrieve the version numbers of the various software components running on an ECU.

And a way to retrieve the date that each of those software components was built.

A way to ensure the code and calibration memory regions have not been altered is provided.