VS Code

Set up VS Code with the Motorcortex extension to build, run and debug a C++ control application on a target.

  7 minute read  

The Motorcortex VS Code extension scaffolds a C++ control application, sets up a cross-compilation toolchain, and builds, runs and debugs the application on a target.

Work through the tabs in order: create the project, then set up a toolchain. Settings and Troubleshooting are references you come back to.


Installing the Motorcortex extension

The installation guide for the Motorcortex VS Code extension is in Software features.

Setting up the project

The extension acts on the project type it detects, so start by creating a project or marking an existing folder as one.

Click the + button in the Developer tools section of the Motorcortex view and choose the C++ control application, or run Motorcortex: Create C++ MCX Control App from the Command Palette (ctrl+shift+p). This creates a folder with the files and structure of a Motorcortex control application.

The scaffold button in the Developer tools section

Open the new folder in VS Code. The Developer tools section now shows the project name and reports its type as a C++ Control App.

Developer tools showing a detected C++ Control App

Setting up the toolchain

There are three ways to build, depending on your development setup:

  • Cross-Remote toolchain, build on local (preferred)

    Builds the application on your local machine and deploys it to the target to run. Uses the Motorcortex cross-remote SDK.

  • Cross-Remote toolchain, build on target

    Builds the application on the target while you develop locally. Uses the Motorcortex cross-remote SDK for IntelliSense.

  • Remote toolchain (Remote Development), build on target

    Builds and runs the application on the target while you develop locally. Uses the VS Code Remote Development extension pack, which the Motorcortex extension installs as a dependency.

Both Cross-Remote options share one setup; where the build runs is a choice you make afterwards in the extension.


Cross-Remote toolchain

This is the preferred way to develop Motorcortex control applications remotely. It uses the Motorcortex Cross-Remote SDK for IntelliSense and build support on your local machine, and deploys and runs the application on the target device.

Prerequisites

Download the latest Motorcortex SDK for your system from the Motorcortex store, for example mcx-rtos-glibc-x86_64-mcx-image-dev-corei7-64-mcx-intel-toolchain-2025.03-0-g0e9d0e9.sh.

Installing

  1. Press the Configure Toolchain button in the Motorcortex view and choose Cross-Remote.

    The configure toolchain button in Developer tools

  2. Choose whether to use a DevContainer. A DevContainer is recommended: it gives a consistent environment, is built into VS Code and works cross-platform. Without one, install the required dependencies on your local machine yourself.

  3. Configure the remote path and the executable name.

    • Remote path: the path on the target where the executable and configs are synced to run and debug. Building on the target syncs the whole workspace to this path.
    • Executable name: the name of the executable built and run on the target. Match the name in your CMakeLists.txt.

  4. Select the file for the option you chose in step 2.

    • DevContainer: the SDK installer, **.sh.
    • No DevContainer: the environment setup file in the installed SDK folder — mcx-cmake-environment, or an environment-setup-* file on an older SDK.

  5. Open the DevContainer, if you chose one, with the Reopen in Container button at the bottom right of VS Code.

  6. Select the CMake kit: ctrl+shift+p → CMake: Select a Kit → MCX Cross-Compile Toolchain.

Usage

You can now build, run and debug your control application with the VS Code build and debug features, and the extension handles deployment and execution on the target. The Developer tools section of the Motorcortex view carries buttons for the same actions.

Build, install, run and debug buttons in Developer tools

The buttons drive tasks and launch configurations that the extension writes into the .vscode folder, so the same workflow is available through the native VS Code UI.


Remote toolchain

This way of developing Motorcortex control applications runs entirely on the target machine, and only the VS Code UI runs locally. The files live on the target, and the terminals inside VS Code run there too, so working with Git needs care.

Installing

  1. Open the Remote Explorer and select Remotes (Tunnels/SSH) in the top bar:

    Remote Explorer showing the Remotes (Tunnels/SSH) view

  2. Add a remote with the + icon next to SSH, and follow the prompts to set up an SSH connection to your target machine.

  3. Open the new SSH connection, in the current window or in a new one.

  4. Install the Motorcortex extension again, on the remote.

  5. Transfer your project files to the target machine, or create a new project there.

  6. Press the Configure Toolchain button in the Motorcortex view and choose Remote toolchain.

    The configure toolchain button in Developer tools

  7. Enter the name of the executable. Match the name in your CMakeLists.txt.


Settings

The Developer tools section of the Motorcortex view shows the settings relevant to the selected toolchain, and you can change them there directly.

The settings that apply to both toolchains:

  • motorcortex.targetIp — IP address of your Motorcortex Target controller
  • motorcortex.targetUsername — SSH username for your Motorcortex Target controller
  • motorcortex.cpp.default_args — default program arguments when running or debugging
  • motorcortex.cpp.executable_name — name of the executable to build and run on the target controller
  • motorcortex.cpp.crossRemoteToolchain.remote_path — remote path on the controller where files are synced
  • motorcortex.cpp.toolchain_base_path — base directory holding the installed toolchains
  • motorcortex.cpp.environment_setup_path — path to the SDK environment setup script, detected during toolchain setup
  • motorcortex.cpp.cmake_toolchain_path — path to the CMake toolchain file for cross-compiling
  • motorcortex.cpp.additional_cmake_args — extra CMake arguments for the configuration step
  • motorcortex.cpp.mcx_packaging_install_prefix — path prefix for installing MCX Packaging on the target

The full list, including the Python client settings, is in VS Code settings.


Troubleshooting

MainControlLoop.h: No such file or directory

You are compiling with g++ directly. Use the CMake build tasks instead.

mcx/core.h: No such file or directory
  • Check that the SDK is installed correctly if you are using the Remote toolchain.
  • Check that Motorcortex is installed on the controller. Deploy an application from the Motorcortex Portal if you are using the Remote Development toolchain.
  • Check that motorcortex.cpp.cmake_toolchain_path points at the SDK toolchain file.
  • If the build succeeds but IntelliSense fails, select the CMake kit: ctrl+shift+p → CMake: Select a Kit → MCX Cross-Compile Toolchain.
Cannot find the executable when debugging
  • Build first, with Ctrl+Shift+B.
  • Check that build/**-debug/<executable_name> or build/**-release/<executable_name> exists, where <executable_name> is the motorcortex.cpp.executable_name setting.
Breakpoints not working (red or unbound)
  • Use the Debug configuration, not Release.
  • Delete the build folder and rebuild: rm -rf build/debug followed by Ctrl+Shift+B.
Failed to start the listener for URL: wss://*:5568 (Address in use)
  • Check that Motorcortex is not running: sudo motorcortex stop.
  • Check that no other instance of your program is running.
Building takes a long time
  • Check that Motorcortex is not running: sudo motorcortex stop.
  • Check that no other instance of your program is running.