Simulink Projects

Simulink Projects

This guide sets up a Simulink model so that cdx build and Dash Design’s CDX Project Tools generate, compile and package it without manual steps. It extends the Quickstart, which builds the hand-written starter without MATLAB. Complete that first build before adding a model.

Alternatively, start with the self-contained Simulink Bench example. Its original stock-block model is created by a MATLAB script rather than a release-specific binary model file, and its adapter demonstrates IPC, fast I/O and persistent XCP parameters without any customer project dependencies.

Checklist

  1. Install the tools, including Arm GNU Toolchain 15.3.rel2 (cdx-runtime\install-tools.cmd offers to install it beside older compilers), MATLAB with Simulink Coder and Embedded Coder, and licensed Ginmake.
  2. Create the project from the project template.
  3. Put the model, its data dictionary and supporting files in model\.
  4. Write model\initialize.m.
  5. Point Ginmake’s workspace output at model\workspaces.
  6. Add the model and initialization script to cdx-project.json.
  7. Check the model configuration and callbacks.
  8. Connect the generated code in CMake.
  9. Save everything in MATLAB, then build in CDX Project Tools or run cdx build.

Project Layout

 1my-project\
 2  cdx-runtime\          Complete runtime release - replace as a whole, do not edit
 3  cdx-project.json      Model, initialization, setup and output paths
 4  CMakeLists.txt        Application build and packaging
 5  CMakePresets.json     cm4-release and cm4-debug presets
 6  model-ipc.json5       Ginmake configuration
 7  ipc\                  DBCs shared with the Dash Design setup
 8  main\                 Application callbacks, version.h and adapters
 9  model\
10    MyModel.slx         Simulink model
11    MyModel.sldd        Data dictionary (optional)
12    initialize.m        Project-owned initialization script
13    workspaces\         Ginmake-generated workspace scripts (do not edit)
14  model-generated\      Generated C staged by cdx (do not edit)
15  ginmake-generated\    Generated IPC C (do not edit)
16  build\                Build output
17  .cdx\                 CLI and Dash Design state (machine-local - do not add to version control)

Generated folders, .cdx\, build\ and cdx-project.local.json belong in .gitignore. The template’s .gitignore already lists them.

Initialization Script

When MATLAB generation is needed, cdx build, cdx matlab and the matching CDX Project Tools steps run this sequence:

flowchart TD
    A["cdx build (terminal or CDX Project Tools)"] --> B["CMake configure + Ginmake IPC<br/>regenerates model\workspaces"]
    B --> C{"Model inputs changed?"}
    C -- no --> F
    C -- yes --> D["matlab -batch in project root<br/>adds cdx-runtime\matlab"]
    D --> E["cdx.generate: run initialize.m,<br/>load model, slbuild, stage C"]
    E --> F["CMake compile + package<br/>.cdxmodel and MDL_FIRM.bin"]
    F --> G["Load Model... / embed + deploy"]

The batch MATLAB starts in the project root. It adds cdx-runtime\matlab to the path and calls cdx.generate. That function runs the configured initialization script in the base workspace, loads the model by its full path and generates code. Afterwards it restores the previous MATLAB path and current folder. cdx.workflow does the same in an already open MATLAB session.

The model folder is therefore not the current folder, and only paths added by the initialization script are available. A complete script for a model in model\ is:

1modelFolder = fileparts(mfilename('fullpath'));
2projectRoot = fileparts(modelFolder);
3
4addpath(modelFolder);
5addpath(fullfile(modelFolder, 'workspaces'));
6addpath(fullfile(projectRoot, 'cdx-runtime', 'matlab'));
7cdx.inputs('base');
Line Why it is required
fileparts(mfilename('fullpath')) Finds folders relative to the script, so it works from the CLI, Dash Design and an interactive session. Do not use pwd-relative or machine-specific absolute paths.
addpath(modelFolder) Simulink finds data dictionaries (.sldd), enumeration classes (for example ENUM_*.m), referenced models and callback helpers through the MATLAB path.
addpath(...'workspaces') Makes the Ginmake workspace scripts and signal classes available, such as ipc_model_can_rx.m, ipc_model_can_tx.m and GemsSignal.m. The folder must match out_dir_workspace.
addpath(...'cdx-runtime', 'matlab') Provides the cdx.* helpers. Batch generation adds this itself, but interactive simulation, model updates and cdx.workflow need it.
cdx.inputs('base') Defines the CDX fast-I/O input signals (CDX_adc_1_raw … CDX_adc_8_valid and CDX_model_adc_*) in the base workspace. Each signal is bound to a getter in cdx_fast_io.h. Needed only when the model reads them, but harmless otherwise.

The CDX_adc_* signals must exist before the model is compiled. A model linked to a data dictionary sees base-workspace signals only when Enable model access to base workspace (EnableAccessToBaseWorkspace) is on. Otherwise, add the definitions returned by signals = cdx.inputs() to the dictionary instead of calling cdx.inputs('base').

The script runs before every generation, so keep it repeatable and non-interactive:

  • Do not save, close or discard models or dictionaries (save_system, bdclose, close_system). Generation refuses unsaved changes.
  • Do not use clear all, close all, cd, dialogs or input.
  • Do not modify the generated workspaces files. They are regenerated from the DBCs.
  • Add further addpath calls for shared libraries or referenced models outside model\, and list external data under codegen_inputs so incremental builds notice changes.

Ginmake Workspace Files

The CMake/Ginmake IPC step regenerates the workspace scripts before MATLAB runs. Set out_dir_workspace in the Ginmake configuration to the folder that the initialization script adds:

{
    target: "CDX",
    out_dir: "ginmake-generated",
    out_dir_workspace: "model/workspaces",
    file_prefix: "ipc_model_",
    generate: { get_set: true, workspace: true, can_rx_workspace: true, can_tx_workspace: true },
}

Keep file_prefix and the PREFIX passed to CDX_RT_generate_ipc identical. The generated scripts (for example ipc_model_can_rx.m and ipc_model_can_tx.m) create the GetSet IPC signals used by the model. Run them from the model’s InitFcn callback or from the initialization script, after the addpath calls.

Project Configuration

Add the model and initialization script to cdx-project.json. Paths are relative to that file:

 1{
 2  "format": 1,
 3  "runtime": "cdx-runtime",
 4  "preset": "cm4-release",
 5  "generated_sources": "model-generated",
 6  "model": "model/MyModel.slx",
 7  "initialization": "model/initialize.m",
 8  "setup": "setups/MyDash.cd6.gdd",
 9  "deployment_setup": "output/MyDash-model.cd6.gdd"
10}

setup and deployment_setup are needed only to embed or deploy. Prefer project-relative paths or %VAR% environment references to absolute paths in a user’s own folders, so the project builds on other machines. Create the deployment output folder before building. See Project configuration for all fields.

Model Configuration

Setting Required value
Solver Fixed-step, discrete (FixedStepDiscrete)
Tasking Single-tasking (EnableMultiTasking off)
Fixed-step size Explicit whole microseconds, for example 0.001 or 0.002 (not auto)
System target file ert.tlc (Embedded Coder)

cdx.generate checks the timing settings, generates code only and stages the period in cdx_model_timing.h. Changing the step requires regeneration.

Model Callbacks

Model callbacks run with the project root as the current folder. A callback such as PostLoadFcn: addpath("workspaces\") therefore adds nothing during a CDX build. MATLAB only warns that the folder does not exist. Move path setup into initialize.m, or build the path from fileparts(get_param(bdroot, 'FileName')).

Callbacks must not leave the model modified. If they do, generation stops with CDX:UnsavedModel.

CMake Integration

The project’s CMakeLists.txt includes the staged sources from model-generated\cdx-generated.cmake and keeps CDX_RT_configure_model and CDX_RT_generate_ipc. Either call the model’s initialize and step functions from your own main\ adapter, or use CDX_RT_configure_simulink. The template’s Simulink section describes both.

Build In Dash Design CDX Project Tools

  1. Save the model and any data dictionaries in MATLAB. MATLAB can stay open.
  2. In Dash Design, choose Setup > CDX Model > CDX Project Tools… (or Tools > CDX Project Tools…) and select the project folder containing cdx-project.json.
  3. Set Compiler to arm-none-eabi-gcc.exe from the 15.3.rel2 installation, for example C:\Tools\arm-gcc-15.3.rel2\bin\arm-none-eabi-gcc.exe. Do not select an older compiler such as VisualGDB’s C:\SysGCC\arm-eabi (GCC 10.3).
  4. Set MATLAB to matlab.exe (for example C:\Program Files\MATLAB\R2023b\bin\matlab.exe) unless MATLAB is on PATH. Set CMake, Ninja and Ginmake too if they are not on PATH.
  5. Click Check Tools.
  6. The first time, and after changing compiler or runtime versions, run Configure Fresh so CMake forgets a cached compiler.
  7. Select Incremental Build (cdx build). Add Embed Setup and Deploy with the display serial to program a CD6. Select MATLAB Generation to force regeneration.
  8. After a successful build, use the Load Model… notification to import the new package into the open setup.

Tool selections are stored in the machine-local .cdx\dash-design.json. Save Tool Paths to Project writes shared defaults to cdx-project.json. Use %VAR% references there, because other users’ installation folders differ. The same build runs from a terminal with cdx build, or from MATLAB with cdx.workflow('full-build', config).

To check the setup interactively, run initialize in MATLAB, open the model and update the diagram (Ctrl+D) before building.

Using CDX from MATLAB

You can run CDX commands from the MATLAB Command Window or a MATLAB script.

  1. Add the runtime’s matlab folder to the MATLAB path.
  2. Select your project configuration and run commands, as below:
1projectRoot = 'C:\work\my-project';
2addpath(fullfile(projectRoot, 'cdx-runtime', 'matlab'));
3config = fullfile(projectRoot, 'cdx-project.json');
4
5cdx.cli('help', config, 'compile');
6cdx.cli('doctor', config, '--operation', 'build');

These helpers use the project’s bundled executable, so you do not need to run the terminal setup scripts inside MATLAB. Required build tools must still be available.

Build Existing Application Code

1result = cdx.cli('compile', config);

This builds and packages the application using existing sources. It does not generate Simulink code or program the display.

Configure the model and initialization script in cdx-project.json, as described in Project Configuration. Save modified models and data dictionaries before generation. The helper refuses unsaved changes.

1result = cdx.workflow('full-build', config);

This generates code in the current MATLAB session. It then stages the sources, builds and packages the application. You need MATLAB, Simulink Coder and Embedded Coder.

To also prepare the configured display setup and program a specific CD6:

1result = cdx.workflow('full-build-deploy', config, ...
2    'Serial', '12345');

Configure the source setup and deployment output paths first, and create the output directory. Without Serial, deployment selects the first available USB display. Network displays require an explicit serial number.

cdx.workflow keeps the full-build, full-build-embed and full-build-deploy current-session API and MATLAB name/value options. It does not parse CLI pipelines or --skip-matlab. To forward new pipelines and flags, use cdx.cli:

1result = cdx.cli('compile+embed', config);
2result = cdx.cli('build+deploy', config, '--skip-matlab', '--serial', '12345');

Calling cdx.cli('matlab+compile', config) instead launches a separate batch MATLAB process. Use cdx.workflow for generation in the current session. See the MATLAB integration guide for individual generation steps, additional options and validation limitations.

Troubleshooting

Problem Next step
Configure model and initialization explicitly Add model and initialization to cdx-project.json.
Unable to resolve the name cdx.inputs Add cdx-runtime\matlab to the path in initialize.m.
Undefined ipc_model_can_rx, GemsSignal or IPC signals Check that out_dir_workspace matches the folder added by initialize.m, then rerun the build so Ginmake regenerates it.
Data dictionary or enumeration class not found Add the model folder, and any shared folders, to the path in initialize.m.
CDX_adc_* or CDX_model_adc_* undefined Call cdx.inputs('base'), or add cdx.inputs() definitions to the data dictionary.
Warning that workspaces is not a folder A callback adds a path relative to the current folder. See Model Callbacks.
CDX:Timing Use a fixed-step discrete, single-tasking model with an explicit step.
CDX:UnsavedModel or CDX:UnsavedDictionary Save in MATLAB, and stop callbacks or initialize.m from changing the model.
MATLAB is not found Select matlab.exe in CDX Project Tools or set tools.matlab in cdx-project.local.json.
Compiler version mismatch or the old compiler is still used Select the 15.3.rel2 compiler, then run Configure Fresh (cdx configure --fresh).