MCUXpresso for VS Code: Combine MCUXpresso or Zephyr projects using AI
Introduction
This tutorial shows how GitHub Copilot AI, along with the MCUXpresso Combine Projects agent, delivered in the MCUXpresso for VS Code extension, can drive the creation of new projects based on selected examples. MCUXpresso SDK and Zephyr examples from NXP provide a great starting point for learning, but often developers want to combine these examples to rapidly develop prototypes. Instead of manually merging files and resolving build conflicts by hand, an engineer describes the intended combined application in plain language and the agent orchestrates every step.
In this scenario, the engineer asks the agent to accomplish an end-to-end task:
Target the FRDM-iMXRT1186 (CM33) board with Zephyr 4.4.
Combine the blinky, shell_module, and hello_world examples, all imported fresh from the repository as Freestanding.
Add shell commands to turn LED blinking on/off and control the blink rate from the UART console.
Clean up the source examples after a successful build.
The agent decomposes this request into a sequence of ordered phases – verifying tool availability, selecting and importing examples, enforcing constraints, detecting conflicts, scaffolding a combined project, merging configuration and source, building, and cleaning up. The sections below follow that same order.
The agent supports both Zephyr (prj.conf + devicetree overlays, Zephyr ARM toolchain) and MCUXpresso SDK (SDK components + linker scripts, Arm GNU Toolchain) project types. The scenario shown here uses Zephyr; MCUXpresso SDK projects follow the same flow with the appropriate SDK repository and toolchain.
The agent only performs actions through the extension's own tools, so every step it takes maps directly to functionality you could also trigger manually from the MCUXpresso for VS Code UI. For all structured choices – SDK type, board confirmation, appType , conflict resolution, and cleanup options – the agent uses the #askQuestion tool to surface clickable buttons in the chat UI to reduce the need to type a letter or number by hand.
System Architecture
MCUXpresso Combine PROJECTS Agent
End-to-End Workflow Overview
📄
Source Projects
blinky, shell_module, hello_world (imported or in workspace)
Merge
🤖
Combine Agent
MCUXpresso Skills Copilot chat agent
Build
📦
Combined Project
combined_ _ single built applicatione
Component
Description
Source Projects
Two or more MCUXpresso Zephyr or MCUXpresso SDK projects targeting the same board. May already be in the workspace or imported fresh by the agent using importExampleFromRepo .
Combine Agent
The MCUXpresso skill files allow the Copilot agent to orchestrate the full workflow: tool verification, example selection and import (Zephyr or MCUXpresso SDK), constraint enforcement, conflict detection, project scaffolding, configuration application, source merge, build with DTS regression check(Zephyr only), and cleanup. Uses #askQuestion for all structured choices.
Combined Project
A new project named combined_ _ , scaffolded from a fresh hello_world example for the same board. The agent merges configuration and source so both functionalities run in the combined app.
Getting started
The engineer describes the combined application in a single natural-language prompt, and the agent carries out the ordered phases below – starting the agent, selecting examples, enforcing constraints, resolving conflicts, scaffolding, merging, building, and cleaning up.
Prerequisites
Before starting you should have:
Visual Studio Code with the MCUXpresso for VS Code extension installed and activated, and GitHub Copilot Chat available.
The MCUXpresso tool set enabled in Copilot Chat – click Configure Tools in the bottom-left corner of the chat input window and make sure MCUXpresso is toggled on.
At least one SDK or Zephyr repository registered in the extension. A Zephyr / Zephyr NXP repository requires a Zephyr ARM toolchain; an MCUXpresso SDK repository requires an Arm GNU Toolchain.
A compatible toolchain installed and reachable from the project's MCUXpresso integrated terminal (installed via the MCUXpresso Installer or the extension's toolchain management).
Examples do not need to be imported beforehand – the agent can import them for you during the flow.
Step 1 – Start the agent
Open Copilot Chat, select the MCUXpresso Combine Projects agent from the agent picker, or type /mcuxpresso-combine-projects in the chat input. The agent immediately verifies that the MCUXpresso extension tools are accessible in this session by calling listProjectsFromWorkspace .
Select the Combine Projects agent or run the /mcuxpresso-combine-projects prompt to start the flow. Phase 0 passes and the agent asks for the SDK type.Select the Combine Projects agent or run the /mcuxpresso-combine-projects prompt to start the flow. Phase 0 passes and the agent asks for the SDK type.
Select the Combine Projects agent or run the /mcuxpresso-combine-projects prompt to start the flow. Phase 0 passes and the agent asks for the SDK type.
Alternatively, you can include all required details in the opening prompt and the agent will proceed without asking for them one by one:
Providing board, SDK version, example names, appType, and cleanup preference in one prompt lets the agent skip the individual selection questions and go straight to board confirmation.
If the tool call succeeds, the agent proceeds to example selection. If it fails – because the MCUXpresso tool set is not enabled – it stops and tells the user how to enable it via Configure Tools.
Throughout the flow the agent uses the #askQuestion tool to present structured choices (SDK type, board confirmation, appType , conflict resolution, cleanup options) as clickable buttons in the chat UI. You never need to type a letter or number by hand. Plain text is accepted as a fallback when #askQuestion is unavailable.
Constraint: the agent will not advance past this point until the MCUXpresso tools are confirmed available in the current chat session.
Step 2 – Select examples
The agent asks for the SDK type (Zephyr or MCUXpresso SDK), then lists the projects currently in the workspace. The engineer chooses which examples to combine – by picking from the workspace list, by naming examples to import fresh, or by mixing both approaches.
When more than one matching repository is installed, the agent asks which one to use, then collects the example names and target board.
For any example not yet in the workspace, the agent runs the full import discovery chain: listRepositories → filter to the chosen SDK type → repository selection (if more than one matching repository is found, the agent presents them as a numbered list and asks which one to use for all imports in this session) → listSupportedBoards → explicit board confirmation → listSupportedExamples → user chooses appType → importExampleFromRepo . After each import, listProjectsFromWorkspace is called to confirm the project is registered. If the project files exist on disk but do not appear in the workspace list, the agent automatically falls back to importProject to register the on-disk folder.
The agent always asks the user to explicitly confirm the resolved board before listing or importing any examples.
The agent resolves the exact template IDs for each requested example and asks for confirmation before importing.
The agent imports all confirmed source examples into the workspace.
Constraints: the SDK type must be chosen explicitly; appType must be chosen by the user for every import – the agent never assumes a default. The board is always confirmed with the user before any example is listed or imported. The chosen repository is reused consistently for every import in the session, including the hello_world scaffold.
Step 3 – Verify constraints
Before any merging begins, the agent enforces three hard constraints across all selected examples:
At least two examples must be in the confirmed set.
Same SDK type – all examples must use the SDK type chosen in the previous step (Zephyr or MCUXpresso SDK).
Same board and core – the BOARD id and variant/core qualifier must be identical across all examples. Different cores of the same SoC do not match.
Constraint: if any gate check fails, the agent stops immediately, reports exactly what is wrong, and waits for the user to correct the problem. It will not fabricate a board match or SDK-type match.
Step 4 – Detect conflicts
The agent scans all selected examples for devicetree, Kconfig, and memory-layout conflicts – pin or pinctrl reuse for different functions, chosen nodes pointing at different UARTs, the same CONFIG_* symbol set to incompatible values, and overlapping flash partitions or memory regions.
Non-conflicting settings – distinct peripheral enables, independent Kconfig flags, additional aliases, non-overlapping memory regions – are auto-merged into the combined project without asking. They appear in an Auto-merged summary.
The conflict report lists auto-merged settings and presents any true conflicts as numbered options for the user to choose from.
Conflicting settings are presented as a numbered list: option A keeps the value from example X, option B keeps the value from example Y, and option C provides a safe combined value where one genuinely exists. The agent records every decision before continuing.
When no true conflicts are found, the agent says so explicitly, lists the full auto-merged configuration union, and continues straight to scaffolding the combined project without asking for any resolution choices.
Constraint: the agent never resolves a conflict silently – every conflict requires an explicit user choice. Non-conflicting settings are always auto-merged without prompting.
Step 5 – Create the combined project
The agent imports a fresh hello_world example for the same board – following the same import discovery chain and asking the user for appType – and uses it as the scaffold for the combined application. The default name is combined_ _ ; the user can accept the default or provide a custom name. The agent asks for both the project name and the appType for the scaffold before importing it.
The agent confirms the combined project name and appType, then imports the fresh hello_world scaffold as the base for the merge.
The agent then applies the conflict resolutions chosen in the previous phase and auto-includes all non-conflicting configuration from every source example – every peripheral enable, Kconfig flag, alias, and memory region that was listed as auto-merged is added without further prompting.
Constraint: the agent never silently drops a setting a source example needed, and never adds settings that were not present in at least one source example.
Step 6 – Merge sources
The agent merges the application source from every example into the combined project so both functionalities run. It inventories each example's source files and CMakeLists.txt entries, then:
Copies source and header files into the combined project, renaming collisions (e.g. main.c → app_blinky.c ) and prefixing any clashing symbols.
Refactors each example's main() into a callable init/run function.
Writes a combined main() that runs both workloads – using separate Zephyr threads if either example blocks or loops forever, cooperative calls if both are short.
Merges CMakeLists.txt source lists, component dependencies, include directories, and linked libraries, removing duplicates.
The merged main.c combines both workloads; prj.conf reflects the union of all required Kconfig settings.
Shared resources – console, GPIO, timers – are reconciled according to the conflict-resolution decisions from the previous phase. Both examples' output is routed to the single chosen console.
Step 7 – Build and verify
The agent builds the combined project using the MCUXpresso for VS Code extension build tools ( buildProject / rebuildProject ). It monitors compile and link errors, iterates on fixes, and reports the final FLASH and RAM usage from the build output.
Build restriction: the agent never invokes cmake , ninja , make , or west build directly in a terminal. All builds, cleans, and rebuilds go exclusively through the MCUXpresso extension tools ( #buildProject , #cleanProject , #rebuildProject ). Running build commands in a raw terminal bypasses the extension's environment and toolchain configuration and will produce incorrect results.
After a successful build the agent provides a full summary: what was combined, the conflicts and their resolutions, the new project name and location, and how to flash the firmware to the target board.
Step 8 – Clean up
Once the build succeeds, the agent asks what to do with the source examples used for combining. It never touches the combined project itself:
A. Keep all source examples in the workspace.
B. Remove all source examples from the workspace (with a separate confirmation for disk deletion).
C. Choose per example – the agent asks about each one individually.
The agent offers three cleanup options for the source examples and asks for explicit confirmation before any disk deletion.
For any removal the agent calls removeProject , asks a follow-up question confirming whether the files should also be deleted from disk, and then re-checks the workspace list to confirm the cleanup is complete.
Constraint: the agent never deletes files from disk without explicit user confirmation. The combined project is never offered for removal.
Verifying the Result
The workflow is successful when all of the following hold:
The verification gate passed: at least two examples, all sharing the same SDK type and the same board and core.
All conflicts were resolved by explicit user choice; all non-conflicting settings were auto-merged.
The combined project (e.g. combined_blinky_shell_module_hello_world ) appears in the workspace (confirm with listProjectsFromWorkspace ).
The build completed without errors and produced a firmware artifact.
The build summary reports the expected FLASH and RAM usage for both combined workloads.
Source examples were handled per your chosen cleanup option
Troubleshooting
Most issues fall into one of the categories below.
Symptom
Likely cause
Suggested action
MCUXpresso tools not available
The MCUXpresso tool set is not enabled in Copilot Chat
Click Configure Tools in the bottom-left corner of the chat input, enable the MCUXpresso tool set, then restart the conversation.
Verification gate fails – board mismatch
Selected examples target different boards or core variants
Re-import the mismatched example targeting the correct board, or replace it with a compatible one.
Import did not register in workspace
importExampleFromRepo succeeded but the project is not listed by listProjectsFromWorkspace
The agent automatically falls back to importProject to register the on-disk folder. If this also fails, manually add the project folder via the MCUXpresso Projects view.
Configure fails after import
Board revision in CMakePresets.json uses the wrong case (e.g. @b instead of @B )
The agent detects and corrects the board revision in CMakePresets.json , cleans the build directory, and re-runs configure and build automatically.
Build fails with stale CMake cache
A previous failed configure left a partial build directory
The agent cleans the build/ directory and re-runs configure before rebuilding. You can also delete the build/ folder manually and run configure again from the MCUXpresso terminal.
Examples
View full article
