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 devicescan 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 Simulinklicence. 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\* . -RecurseThis 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.ps1Accept 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.
-
In Dash Design, create a new setup for your CD6 type.
-
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 1toAnalogue 8channels to the model, and adds channelsMDL_CTR,MDL_CPU_TEMPandMDL_CPU_LOADfor the model’s outputs. -
On the Design tab, add value gauges showing
Analogue 1andMDL_CTR. -
Save the setup, for example as
hello.cd6.gddin the project folder. -
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_CTRshows the input in raw counts, about 704 per volt, and follows it.MDL_CPU_TEMPandMDL_CPU_LOADapproximately 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 12345embed 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. |