How to handle .mat file initialization in Simulink models

EHANDBOOK Container-Build has a known limitation: it does not process MATLAB workspace variables or load external .mat files during model conversion or mask generation. This limitation can be problematic when your Simulink model contains custom library blocks whose mask displays depend on data stored in external .mat files.

This how-to guide explains a workaround that uses Simulink’s PreLoadFcn callback to ensure your .mat file is loaded when EHANDBOOK Container-Build processes your model.

Background

The Problem

Custom Simulink library blocks often use mask parameters that retrieve values from the MATLAB base workspace. These values may be defined in external .mat files that are loaded manually before opening the model in your local MATLAB environment.

When EHANDBOOK Container-Build launches a MATLAB instance to process your model, it does not load these .mat files into the workspace. As a result, the mask display code fails to find the required variables, causing incorrect or error-state rendering of your custom blocks in the documentation.

Example mask visualization code that depends on workspace variables
try
    % Get variable name from base workspace
    TmpObj = evalin('base', ObjName);
    BlockUserData = get(TmpObj, 'UserData');
    DisplayString = BlockUserData.ObjectName;
catch
    DisplayString = 'Input not found!';  % Shows when .mat file is not loaded
end

The Solution: PreLoadFcn Callback

Simulink models support a PreLoadFcn callback that executes automatically when the model is opened. By placing a reference to your .mat file in this callback, you ensure the data is loaded into the MATLAB workspace—both when you open the model locally and when EHANDBOOK Container-Build processes it.

Step-by-Step Implementation

Step 1: Create a MATLAB Script to Load Your .mat File

Create a new MATLAB script file (e.g., LoadModelData.m) that contains a single command to load your .mat file:

load('C:\path\to\your\MAT\file.mat')

Replace C:\path\to\your\MAT\file.mat with the actual path to your .mat file.

You can also use a relative path if your .mat file is located relative to your model or project directory:

load('.\data\file.mat')

This approach is recommended for portability.

Step 2: Add PreLoadFcn to Your Simulink Model

In Simulink, open your model and access the model properties:

  1. Go to Modeling > Model Settings > Model Properties

  2. Select the Callbacks tab

  3. In the PreLoadFcn field, enter the name of your script (without the .m extension):

    LoadModelData

Ensure that the directory containing your .m script is either:

  • In the MATLAB path

  • In the same directory as your model

  • In a location that you will specify to EHANDBOOK Container-Build (see Step 4)

Step 3: Verify Locally

Before running EHANDBOOK Container-Build, verify that your setup works in your local MATLAB environment:

  1. Close your Simulink model completely

  2. Re-open the model

  3. Confirm that the .mat file is loaded (check the MATLAB workspace)

  4. Verify that your custom block masks display correctly

Step 4: Configure EHANDBOOK Container-Build

When running EHANDBOOK Container-Build, pass the directory containing your .m script via the -simlib parameter:

eHandbookCB.exe ^
  -i ".\Input" ^
  -o ".\Output" ^
  -n "YourContainerName" ^
  -simlib "C:\path\to\script\directory" ^
  <other-parameters>

If your script directory is a subdirectory of your project, you can use:

-simlib ".\scripts"

The -simlib parameter accepts multiple paths separated by commas. If you already use -simlib for other libraries, add your script directory to the list:

-simlib ".\scripts,C:\Program Files\MATLAB\R2024b\toolbox\simulink"

Complete Example

Here is a complete example setup:

Project Structure:

MyProject/
├── models/
│   └── MyModel.slx
├── scripts/
│   └── LoadModelData.m
└── data/
    └── ModelParameters.mat

LoadModelData.m:

load('.\data\ModelParameters.mat')

EHB-CB Command:

set EHB_CB_PATH=C:\Program Files\ETAS\EHANDBOOK-Container-Build
set MATLAB_PATH=C:\Program Files\MATLAB\R2024b

%EHB_CB_PATH%\eHandbookCB.exe ^
  -i ".\models" ^
  -o ".\output" ^
  -n "MyDocumentation" ^
  -simlib ".\scripts,%MATLAB_PATH%\toolbox\simulink" ^
  -gensvg

Troubleshooting

The .mat file still is not loaded

  • Verify that your PreLoadFcn script name is correct (no .m extension)

  • Ensure the directory containing the script is included in the -simlib parameter

  • Check the EHANDBOOK Container-Build log file for any callback execution errors

The script path is not found

  • Use absolute paths if relative paths do not work

  • Verify the path exists and uses the correct directory separators (forward slashes / work in both Windows and Unix)

  • Ensure the path is included in the -simlib parameter (not -matlabpath)

My model does not open locally with the PreLoadFcn

  • Verify the script file exists and is syntactically correct

  • Test the script in MATLAB by running it manually from the Command Window

  • Check that the script does not contain errors that would prevent execution

Related Topics