Quickstart: Hello World

CDX Runtime Quickstart

The CDX Model Runtime runs your own application, a Simulink model or C code, on the CD6’s dedicated Cortex-M4 model processor, alongside the display firmware. The model receives dash channel values, runs at a fixed rate and sends results back as new dash channels. The display setup can then show, log or transmit them like any other channel. Use a model for control strategies, calculations and logic beyond what a Dash Design setup can express.

This quickstart builds the supplied starter application, a “hello world” that echoes an analogue input back to the dash, and runs it on a CD6. You do not need MATLAB.

flowchart LR
    A["Create project"] --> B["Install tools"] --> C["Build"]
    C --> D["Load into a Dash Design setup"] --> E["Upload and check"]

What You Need

  • A CD6 with model-runtime firmware, connected to your PC by USB. cdx devices can also list other GEMS displays, but they cannot run models.
  • GEMS Dash Design with CDX Model support, from GEMS downloads.
  • GEMS Ginmake 2.88 or newer, with a Ginmake Simulink licence. Obtain both from GEMS and install the licence using Dash Design.
  • This runtime release, cdx-runtime-<version>.zip.

The install script below provides the remaining build tools: the Arm compiler, CMake and Ninja.

Create the Project

Open PowerShell in the folder containing cdx-runtime-<version>.zip. Replace <version> with your downloaded release version, then run:

1New-Item hello-cdx -ItemType Directory
2cd hello-cdx
3Expand-Archive '..\cdx-runtime-<version>.zip' .
4Copy-Item .\cdx-runtime\examples\project-template\* . -Recurse

This extracts the runtime into a cdx-runtime subfolder and copies the contents of the starter template, including its .gitignore, into the project root:

1hello-cdx\
2  cdx-runtime\        The complete downloaded runtime - do not edit.
3  main\               Application integration code.
4  ipc\                DBC files for CD6 <=> Model communication.
5  CMakeLists.txt      CMake build script for the project
6  CMakePresets.json   CMake toolchain presets for the project
7  cdx-project.json    CDX project configuration, used by the `cdx` command-line tool.
8  model-ipc.json5.in  GEMS ginmake tool configuration file template.

Keep your project files outside cdx-runtime. You can then replace the entire runtime folder during updates without affecting them. Consider using source control such as git, with cdx-runtime as a submodule.

Install the Tools

From the project root, run the signed installer supplied with the runtime:

1.\cdx-runtime\install-tools.ps1

Accept its offers to install Arm GNU Toolchain 15.3.rel2 to C:\Tools\arm-gcc-15.3.rel2, CMake and Ninja. It never changes or removes existing compilers. From Command Prompt, or if PowerShell scripts are blocked, run cdx-runtime\install-tools.cmd instead.

See Installing Tools for the script’s options, manual installation and compiler selection.

Build

Run these commands from the project root, one at a time. Stop if a command fails. Adjust the compiler path if you installed it elsewhere.

1$env:PATH = "C:\Tools\arm-gcc-15.3.rel2\bin;$env:PATH"
2.\cdx-runtime\setup-cdx.ps1
3cdx verify-release --runtime cdx-runtime
4cdx doctor --operation build
5cdx compile
6cdx verify-image --image build\cm4-release\MDL_FIRM.bin
Command Purpose
setup-cdx.ps1 Adds the cdx command-line tool to this terminal’s PATH. Repeat in each new terminal. From Command Prompt, use cdx-runtime\setup-cdx.cmd.
verify-release Checks the runtime’s files against its release manifest.
doctor Checks that the build tools are available. It cannot confirm the Ginmake licence.
compile Generates the IPC code with Ginmake, compiles and packages the application.
verify-image Checks the finalized firmware image without changing it.

The build produces build\cm4-release\CD6-project-template.cdxmodel, the model package that you load into Dash Design. It contains the finalized firmware, MDL_FIRM.bin, and the DBC files that describe the model’s inputs and outputs. Never deploy MDL_FIRM.raw.bin: it will not run on the CD6.

Run cdx to list the commands, or cdx help <command> for help with one. The CDX CLI Guide covers terminal shortcuts, MATLAB use and all commands.

Run It on a CD6

A .cdxmodel package is not a complete display setup. Load it into a Dash Design setup, then upload the setup to the display. See Configuring with Dash Design and the Dash Design manual for general setup editing.

  1. In Dash Design, create a new setup for your CD6 type.

  2. On the Setup tab, open the CDX Model panel and click Load CDX Model…. Select build\cm4-release\CD6-project-template.cdxmodel, choose Embedded in setup, then click Load Model.

    Dash Design sends the setup’s Analogue 1 to Analogue 8 channels to the model, and adds channels MDL_CTR, MDL_CPU_TEMP and MDL_CPU_LOAD for the model’s outputs.

  3. On the Design tab, add value gauges showing Analogue 1 and MDL_CTR.

  4. Save the setup, for example as hello.cd6.gdd in the project folder.

  5. Connect the CD6 by USB and choose File > Upload To Display (F7). The model firmware is programmed with the setup.

Check It Is Running

A successful upload does not prove that the model is running. Apply a voltage to analogue input 1 and vary it:

  • MDL_CTR shows the input in raw counts, about 704 per volt, and follows it.
  • MDL_CPU_TEMP and MDL_CPU_LOAD approximately repeat the Analogue 1 and Analogue 2 voltages. Despite their names, they are demonstration values, not processor measurements.

The starter sends its outputs every 5 ms. It does not print to a console.

Deploy From the Command Line (Optional)

After saving a setup, the CLI can embed each new build into a copy of it and upload without using the Dash Design window. Replace 12345 with the serial number shown by cdx devices:

1cdx doctor --operation deploy
2cdx compile
3cdx embed --setup hello.cd6.gdd --output run.cd6.gdd
4cdx devices --json
5cdx deploy --setup run.cd6.gdd --serial 12345

embed writes the package into a separate deployment copy and leaves hello.cd6.gdd unchanged. deploy uploads that copy only. Without --serial, it selects the first USB display. Uploads report model_startup_verified: false, so repeat the signal check above.

Unattended upload fails, rather than prompting, for a mismatched display type, a nonempty log or a setup that exceeds the display’s memory. Resolve these in Dash Design. See Deploying to a display and pipelines, such as cdx compile+deploy.

Next Steps

To… Read
Understand how the starter works and replace it with your own code Application Template
Learn what models are for and how they connect to the dash Custom Models overview and Model Integration
Build a Simulink model Simulink Projects and the Simulink Bench example
Write callbacks in C Echo and Calibration example and the API reference
Look up a command, pipeline or MATLAB helper CDX CLI Guide
Configure tools or select another compiler Installing Tools
Move to a newer runtime release Updating the Runtime and Revision History
Rebuild or debug the runtime library Rebuilding the Runtime
Read everything offline CD6 manual

Everyday Commands

Run these from the project root, after setup-cdx.

Task Command
Rebuild after editing C sources cdx compile
Build for debugging cdx compile --preset cm4-debug. Do not build Release and Debug at the same time.
Clean build outputs cdx clean, then cdx compile
Discard a cached compiler cdx configure --fresh, then cdx compile. Requires CMake 3.24+.
Generate Simulink code and build cdx build. See Simulink Projects.
See commands and options cdx --help or cdx help compile

Troubleshooting

Problem Next step
cdx is not found Run the setup command again in the terminal you are using. Alternatively, use cdx-runtime\bin\cdx.exe in place of cdx.
A build tool is missing Check its executable directory is on PATH, reopen the terminal and rerun cdx doctor --operation build.
Compiler version mismatch Run cdx-runtime\install-tools.cmd to install/select the exact version in release-manifest.json beside older compilers, then run cdx configure --fresh (or Configure Fresh in CDX Project Tools) and rebuild.
CMake still selects the old compiler Changing PATH does not replace a cached compiler. Select the intended toolchain, run cdx configure --fresh (CMake 3.24+), then cdx compile. Settings present only in the old cache are discarded.
Dash Design reports a channel name conflict or missing channel when loading the model Model input signals must match existing numeric channels by name, ignoring case and punctuation. Start from a new CD6 setup, or rename the conflicting channels.
Configure setup or supply --setup cdx embed and cdx deploy need a saved display setup. Follow Run It on a CD6. Building alone needs none.
A USB display is listed but rejects the model Listing a device does not imply CDX support. Use a CD6 with model-runtime firmware and a matching CD6 setup.
The upload succeeds but MDL_CTR does not change Check that the setup embeds the newly built package, that analogue input 1 is wired and changing, and that the display firmware supports models.
Upload fails with Cannot implicitly convert type 'int' to 'bool' An older CLI mishandles Dash Design job flags. Replace the complete runtime with the current release, not only its executable.
Deployment preflight reports missing SupportsCdxModelImageDescriptor or an unsupported descriptor Install a compatible Dash Design release. The display-mismatch override cannot bypass format compatibility checks.
Release verification fails Replace the runtime with a clean GEMS release. Do not delete the manifest or disable checks to make an ordinary build pass.