Quick Start

Note

The Workspace Setup, Import Application, and Create New Application panels are designed for Zephyr projects only. While CMake projects can access these panels, they will not function correctly. For CMake projects, use File → Open Folder to open your project directory, then configure settings using the Configure Settings Panel available under Configuration in the onsemi Studio Activity Bar, or manually edit .vscode/settings.json.

Workspace and Tools Setup (Zephyr Projects Only)

Open the Command Palette (Ctrl+Shift+P) and run:

onsemi: Workspace and Tools Setup

This opens the interactive setup panel with two operation modes:

• Express Mode - Fully automated installation (recommended for first-time users)

• Advanced Mode - Granular control over individual tool selection and installation

Express Mode Workflow (Recommended)

Express Mode streamlines the setup process by automatically installing all required tools. The panel guides you through three main steps:

Step 1: Configure Repository

Select your workspace source type:

• GitHub Repository: Enter repository URL and branch/tag, choose installation location, then click “Install” to clone

• Local Archive: Browse to a zipped SDK folder, choose extraction location, then click “Install” to unzip and register

• Local Workspace: Browse to an existing SDK/repository folder to register with the extension

Fig. 1 Express mode configuration panel showing repository setup

GitHub Authentication

If accessing private repositories, you’ll be prompted to authenticate:

• Complete the authentication steps in your browser

• Once authenticated, return to VS Code

• The extension will proceed with repository cloning

Fig. 2 GitHub authentication during workspace setup

Step 2: Configure Tools

• The panel automatically identifies required development tools

• All necessary compilers, debuggers, and dependencies are installed automatically

• No manual tool selection needed

Fig. 3 Configure tools installation progress

Step 3: Finish

• Verify installation summary

• Complete setup and begin working with your projects

Note

For CMake Projects: Use File → Open Folder in VS Code to open your existing CMake project directory. Then use the Configure Settings Panel UI (onsemi Studio Activity Bar → Configuration → Configuration Settings) to set up your toolchain and build configurations.

Import Application (Zephyr Projects Only)

Open the Command Palette (Ctrl+Shift+P) and run:

onsemi: Import Application

The import panel guides you through:

• Select SDK/Repository: Choose from configured repositories or browse for local folders/archives

• Choose Toolchain: Select an existing toolchain or browse for toolchain installation path

• Select Board Vendor and Target Board (Zephyr only): Choose the board vendor, then select the specific target board from the available options

• Select Application: Select an application from the chosen sdk/repository

After import, the project is added to your VS Code workspace with:

• Configured build settings in .vscode/settings.json

• Selected toolchain and board

Fig. 4 Import Application panel showing workspace and sample selection

Tip

Copy Sample Option: When importing, you can enable the “Copy Sample” option to copy the sample to a different directory. This helps avoid long path issues on Windows and provides better organization.

Note

For CMake Projects: Use File → Open Folder to open your existing CMake project. Then use the Configure Settings Panel UI (onsemi Studio Activity Bar → Configuration → Configuration Settings) or manually edit .vscode/settings.json with your toolchain and build settings.

Create New Application (Zephyr Projects Only)

Open the Command Palette (Ctrl+Shift+P) and run:

onsemi: Create New Application

Create a new application from scratch:

• Select SDK/Repository: Choose the sdk/repository for the new application

• Choose Template: Select whether to create an empty application or start from an existing sample (the “From Sample” tab is active by default)

Fig. 5 Create New Application panel showing template selection

• Configure Project: Enter the Application Name and Save Location for your new application

• Environment Configuration:

  • Toolchain: Select the toolchain for building

  • Board Vendor: Choose the board vendor (Zephyr)

  • Target Board: Select the target board (Zephyr)

• Click Create Application to create your new application

Fig. 6 Create New Application panel showing Configure Project and Environment Configuration

Note

For CMake Projects: Create your CMake project structure manually, then use File → Open Folder to open it in VS Code. Use the Configure Settings Panel UI (onsemi Studio Activity Bar → Configuration → Configuration Settings) or manually edit .vscode/settings.json with your build settings.

Working with Projects

Once you have projects in your workspace, you can:

From Explorer and onsemi Studio Activity Bar:

Right-click on project folders to access:

• Build, Clean, Rebuild

• Configure (CMake projects)

• Flash (Zephyr projects)

• Debug (Start debugging with active ELF)

• Memory Reports (Zephyr projects)

• Debug Files submenu: - Select Active ELF - Clear Active ELF - Rescan ELFs

• Open in onsemi Studio Terminal (Opens terminal with proper environment)

Application View

After importing or creating projects, they appear in the Application View with an organized structure:

• Configuration

  • Active Configuration: Quick selector for build configurations

  • Board: Change target board (Zephyr Projects)

  • Toolchain: Switch between registered toolchains

• Actions

  • Build: Compile the project

  • Clean: Remove build artifacts

  • Clean and Rebuild: Clean then build

  • Flash: Load firmware to the board (Zephyr Projects)

  • Configure: Configure the project (Bare-metal CMake Projects)

  • Debug: Open Debug Configuration Panel

  • KConfig Config: Run menuconfig or guiconfig (Zephyr Projects)

• Documentation: Text, RST, and MD files

• Header Files: All .h files

• Source Files: All .c files

• Output Files: Build outputs (*.elf, *.map, *.dts, .config)

• Components: All source files compiled into the final output

• Configuration: Kconfig and DeviceTree files (Zephyr Projects)

Fig. 7 Application view showing project structure and actions

Project Terminal

Open an integrated terminal with your project’s environment already configured:

Command: Right-click project folder → “Open Terminal”

The terminal automatically configures:

• PATH Environment: Includes toolchain binaries and required tools

• Python Virtual Environment: Auto-activated for projects (if configured in .vscode/settings.json)

• Project Environment Variables: All project-specific variables from settings

• Working Directory: Set to your project root

Configure Project Settings

For more control over project settings:

1. Expand your project in the Application View

2. Under Configuration, click “Configure Settings”

3. The Configure Project Settings Panel opens

Fig. 8 Configure Project Settings panel

The panel provides:

• Root Project Path: Points to the root project directory

• Toolchain Path: Path to your toolchain installation

• Python Environment Path: Path to the virtual environment folder

• Build Configurations: Manage multiple build configurations

  • Add new configurations using the “+” button

  • Clone existing configurations using the “Clone” button

  • Toggle Active switch to set the active configuration

  • Configure build-specific settings (board, sysbuild, pristine mode, args, environment variables)

• Save Changes: Click the “Save” button after making changes

Debugging Your Application

Prerequisites

• J-Link debugger connected to your target board

• J-Link GDB Server (JLinkGDBServerCL.exe) must be in system PATH or manually specified

Quick Start Debugging

1. Build your project first to generate the ELF file

2. Select Active ELF (automatic or manual):

   • Automatic: The extension auto-detects and selects the ELF file from your build directory

   • Manual: Right-click project → Debug Files → Select Active ELF

3. Run the Debug command to open the Debug Configuration Panel:

   • Right-click project folder → onsemi: Project: Debug

The panel provides:

• Configuration management (create, edit, duplicate, delete)

• Visual editors for general settings, target configuration, runtime options, command customization, UART settings, and peripheral inspector

• Real-time JSON preview

• Task integration

Configuring Debug Settings

Target Tab

1. Device Name: Enter your target device name (e.g., Cortex-M0+)

2. GDB Server Path: Verify the path to JLinkGDBServerCL.exe

   • Default: Should be auto-detected if J-Link is in PATH

   • If not found, click Browse to locate it

3. Connection Settings:

   • Host: localhost (default)

   • Port: 2331 (default)

Fig. 9 Debug Configuration Panel - Target Configuration

Initialization Tab

Configure initialization settings for your target device:

1. Reset Command: Command sent to reset the target device

   • Reset Timing: Controls when the target device is reset during programming

     • Before Programming: Reset before loading program

     • After Programming: Reset after loading program

     • Always: Reset before and after programming

     • Never: No automatic reset

   Important

   Use “Never” when running code from RAM or when reset interferes with debug session.

2. Initialization Commands: Commands executed after connecting to target but before running

   • Command Generation Options: Automatic generation of common GDB commands

     • Include Load Command: Load program load to target

     • Set Program Counter: Set CPU program counter to specific address or symbol (e.g., Reset_Handler, main, or 0x08000000)

     • Set temporary breakpoint: Set temporary breakpoint tbreak at a function name (e.g., main)

     • Output display format: Controls how GDB displays numeric values (addresses, register contents, etc.)

   • Generated Commands Preview: Shows the actual GDB commands that will be executed

   • Additional Commands: Enter custom GDB commands to execute after the generated commands

3. Pre-Run Commands: Commands executed after loading the program but before start of execution

   • Additional Commands: Enter the actual GDB commands to send

4. Custom Reset Commands: Enter custom reset commands when standard reset is insufficient

Fig. 10 Debug Configuration Panel - Initialization Commands

GDB Settings Tab

1. Debugger Executable: Verify path to GDB executable

   • Should point to your toolchain’s GDB (e.g., arm-zephyr-eabi-gdb.exe, arm-none-eabi-gdb.exe)

   • Click Browse if you need to change it

Fig. 11 Debug Configuration Panel - GDB Settings

Peripheral Tab

Configure SVD (System View Description) file for viewing and debugging microcontroller peripheral registers during debug sessions:

1. SVD File Path: Browse and select the SVD file for your target device

   • SVD files provide detailed register layouts and bit field descriptions

   • Enables viewing and modifying peripheral registers in real-time during debugging

Fig. 12 Debug Configuration Panel - Peripheral Inspector

Starting the Debug Session

• Program Path: The extension automatically resolves the active ELF file path. You can use the variable ${command:onsemi.getActiveElfPath} or specify a workspace-relative path using ${workspaceFolder}.

• Click “Start Debugging” to debug the program (with breakpoints)

• Click “Run Program” to flash the program without debugging

Note

Selecting Active ELF File: When multiple ELF files are present in your project, use the bottom status bar to select the active ELF file for debugging. If the Debug Configuration panel is already open when you change the active ELF in the status bar, you must save the Debug Configuration for the panel to display the updated ELF path.

Fig. 13 Start debugging

Troubleshooting Debug Issues

If program fails to load:

1. Verify GDB Server Path points to correct JLinkGDBServerCL.exe

2. Check Debugger Executable in the GDB Settings Tab points to the correct GDB

3. Ensure your J-Link debugger is connected and detected

4. Try debugging again