See :download:`Download the extension for macOS/Windows here <_downloads/openair-vscode-ext-0.0.3.vsix>`.

Vscode Plugin
#############

Installation
************

1. Select View->Extensions

.. figure::  readme_images/init_1.png
     :align: center

.. raw:: html

   <br><br>
2. Click on 3 dots to the right and select “Install from VSIX…”

.. figure::  readme_images/init_2.png
     :align: center

.. raw:: html

   <br><br>

Environment Setup for New Starter
*********************************
1. Open a folder in VS Code to use as the root workspace for the Zephyr project.

2. Locate the OpenAir extension in the extension view

.. figure::  readme_images/openairext_locate.png
     :align: center

.. raw:: html

   <br><br>

3. In the Setup view, click Zephyr IDE Configuration to check the environment status

.. figure::  readme_images/openairext_env_status.png
     :align: center

.. raw:: html

   <br><br>

4. In the Zephyr IDE Configuration, follow the setup steps to prepare the environment for Zephyr development prerequisites.

.. note::
   The time required depends on your internet quality.

.. figure::  readme_images/openairext_env_update.png
     :align: center

.. raw:: html

   <br><br>

Use existing virtual environment
********************************

1. Open an existing Zephyr project workspace.
You can reuse the existing virtual environment and SDK on your computer by
specifying their paths in the Setup view, avoiding the need to repeat earlier
steps in Zephyr IDE Configuration.

.. figure::  readme_images/openairext_env_reuse.png
     :align: center
.. raw:: html

   <br><br>

.. note::
   The virtual environment folder must be named ``.venv`` for proper integration with the VS Code extension.

Build OpenAir applications
**************************

1. In the West Build view, select applications supported by OpenAir from "App Source".

.. figure::  readme_images/openairext_appsource.png
     :align: center

.. raw:: html

   <br><br>

2. Choose from several predefined configurable combinations in Sysbuild Test Case.
Boards are also selectable.

.. figure::  readme_images/openairext_sysbuildcase.png
     :align: center

.. raw:: html

   <br><br>

.. note::
   For experienced users, select Pristine Build Opts defined by Zephyr and add Extra Build Opts.

3. Press the upper green triangle button to start the build. The progress appears in Output view.

.. figure::  readme_images/openairext_build_progress.png
     :align: center

.. raw:: html

   <br><br>


Flash the application to the board
**********************************

1. In West Flash view, select the target serial number foreach Atmosic
reference design interface auto-detected by the extension. For experienced users,
you can choose which storage to erase and which application domain to program.

.. figure::  readme_images/openairext_flash_serial.png
     :align: center

.. raw:: html

   <br><br>

Press the upper green triangle button to start flashing. Progress appears in the Output view.

.. note::
   Windows users new to Atmosic reference design interfaces may see a dialog asking
   to grant permission to install the RDI driver.
   Please grant to install to continue the process.

.. figure::  readme_images/openairext_windows_rdi.png
     :align: center

.. raw:: html

   <br><br>

.. note::
   After installation, switch windows using Alt+Tab and click OK on the pop-up message to continue.

.. figure::  readme_images/openairext_post_windows_rdi.png
     :align: center

.. raw:: html

   <br><br>


Debug the application
*********************

This section explains how to set up the debug environment and run Cortex-Debug
with the OpenAir VS Code extension.

Prerequisites
=============

Before debugging, complete the OpenAir environment setup and install the
debug-related tools:

* OpenAir workspace (West + Python venv + SDK) to build Zephyr applications
* **SEGGER J-Link** (JLinkGDBServer) for on-chip debug via a J-Link probe
* **Cortex-Debug** extension (``marus25.cortex-debug``) for the VS Code debug UI
* A built application ELF (``zephyr.elf``) as the symbol file
* A J-Link probe connected to the target

1. Set up the debug environment
===============================

Open the Configuration Panel
----------------------------

1. Open your OpenAir / Zephyr workspace in VS Code.

2. Open the Command Palette (``Ctrl+Shift+P`` / ``Cmd+Shift+P``).

3. Run **OpenAir: Open Configuration Panel**.

   Or use **OpenAir: Start Environment Setup** and choose a starting step.

Complete the setup steps
------------------------

Run or verify each step until the status shows complete. Click **Refresh Status**
after installs finish.

================  ============================================================
Step              What it does
================  ============================================================
**Step 0**        Install system dependencies (CMake, Ninja, etc.)
**Step 1**        Create Python venv and install West
**Step 2**        West init & update
**Step 3**        Install OpenAir Python packages
**Step 4**        Install Zephyr / West SDK toolchain (``arm-zephyr-eabi-gdb``)
**Step 5**        Check **JLinkGDBServer** (SEGGER J-Link)
**Step 6**        Check **Cortex-Debug** VS Code extension
================  ============================================================

.. figure::  readme_images/openairext_env_install_debug_dep.png
     :align: center

If JLinkGDBServer is missing:

1. Run **OpenAir: Step 5 - Install JLinkGDBServer**, or click the step in the
   Configuration Panel.

2. Choose **Open Download Page**.

3. Download and install the `SEGGER J-Link software package
   <https://www.segger.com/downloads/jlink/>`_.

4. Click **Refresh Status** in the Configuration Panel.

.. note::
   On **Windows**, the extension looks under ``%ProgramFiles%\\SEGGER\\``
   (for example ``JLink_V8.12a\\JLinkGDBServerCL.exe``) and prefers the newest
   versioned install. After install, ensure ``JLinkGDBServer`` /
   ``JLinkGDBServerCL`` is available on your system.

If Cortex-Debug is not installed or is disabled:

1. Run **OpenAir: Step 6 - Install Cortex-Debug**, or click the step in the
   Configuration Panel.

2. Choose **Install Extension** (or **Open Extension Page** to install
   manually).

3. If VS Code prompts you, **reload the window**.

4. Click **Refresh Status** in the Configuration Panel.


2. Build your application
=========================

Debugging requires a built ELF. Configure and build from the **Build** view in
the OpenAir sidebar.

Enable Thread Monitor
---------------------

Thread Monitor adds Kconfig options at build time so you can inspect thread
names, monitor state, and runtime statistics while debugging.

When **Enable Thread Monitor** is **On**, the extension stores these flags in
**Extra Build Opts** and passes them to **West Build**:

========================================  =====================================
Flag                                      Purpose
========================================  =====================================
``-DCONFIG_THREAD_MONITOR=y``             Enable Zephyr thread monitor support
``-DCONFIG_THREAD_NAME=y``                Keep human-readable thread names
``-DCONFIG_THREAD_RUNTIME_STATS=y``       Collect thread runtime statistics
========================================  =====================================

To enable or disable Thread Monitor:

1. Open the **OpenAir** sidebar and select the **Build** view.

2. Click the **Enable Thread Monitor** row to toggle:

   * **On** — flags are added to Extra Build Opts
   * **Off** — flags are removed

.. figure::  readme_images/openairext_enable_thread_monitor.png
   :align: center

.. raw:: html

   <br><br>

.. note::
   Toggle Thread Monitor before you build. If you change it later, rebuild so
   the ELF used for debugging includes the updated Kconfig settings.

Build the application
---------------------

1. Set **Application Source** (for example
   ``openair/samples/bluetooth/hci_vendor``).

2. Set **Board**.

3. Optionally set **Build Dir** (default: ``build``).

4. Run **West Build**.

Expected ELF path (sysbuild layout)::

   {buildDir}/{appFolder}/zephyr/zephyr.elf

Example::

   build/atm3405_hci_vendor/hci_vendor/zephyr/zephyr.elf

3. Generate the debug launch configuration
==========================================

After a successful build (and with the SDK path known):

1. Open the OpenAir **Build** view in the sidebar.

2. Click **Generate Debug Launch** (debug icon), or run
   **OpenAir: Generate Debug Launch Config** from the Command Palette.

.. figure::  readme_images/openairext_generate_debug_launch.png
   :align: center

.. raw:: html

   <br><br>

The extension writes or updates ``.vscode/launch.json`` with a configuration
named **OpenAir Debug**.

.. note::
   Windows users need to manually change the driver of Atmosic reference design
   interface to jlink driver before debugging. Go to Device Manager, expand the
   category "Universal Serial Bus devices" and look for "BULK interface".
   Right click and select "Update Driver". Choose "Browse my computer for
   driver software" and select "Let me pick from a list of device drivers on my
   computer". Then select the "SEGGER J-Link" from the list. Or select "Search
   for drivers in this location" and browse to the SEGGER driver folder.

The following screenshots illustrate the driver update steps:

.. figure::  readme_images/openairext_win_dev_mgr.png
     :align: center

     Device Manager: locate "BULK interface" under "Universal Serial Bus
     devices".

.. raw:: html

   <br><br>

.. figure::  readme_images/openairext_win_update_jlink_drv.png
     :align: center

     Update Driver dialog: select "SEGGER J-Link" from the driver list.

.. raw:: html

   <br><br>

.. figure::  readme_images/openairext_win_update_jlink_done.png
     :align: center

     Confirmation that the J-Link driver was installed successfully.

.. raw:: html

   <br><br>

.. note::
   If the ELF is missing, the configuration is still written, but you must
   build first before starting debug. If the SDK / GDB path is not found, fix
   **Step 4** or set the Zephyr SDK path (**Set Zephyr SDK Path**).

4. Run the debug session
========================

After you build and **re-flash** the application to the board (see
`Flash the application to the board`_ above), start a debug session as
follows:

1. Connect the **J-Link probe** to the target board and to the PC.

2. Power the board.

3. Open the VS Code **Run and Debug** view (``Ctrl+Shift+D`` /
   ``Cmd+Shift+D``).

.. figure::  readme_images/openairext_run_n_debug.png
   :align: center

.. raw:: html

   <br><br>

4. Select **OpenAir Debug** in the configuration dropdown.

5. Press **Start Debugging** (``F5``).

Cortex-Debug starts the J-Link GDB server, loads symbols from the ELF, and
stops at ``main`` (or continues according to your breakpoints).

Debug and Thread Monitor views
------------------------------

While the session is running, use these VS Code views together:

* **Run and Debug** — breakpoints, call stack, variables, watches, and the
  usual step / continue controls from Cortex-Debug.
* **xRTOS** — Zephyr thread monitor data (thread names, state, and runtime
  statistics) when Thread Monitor was enabled at build time.

Switch between **Run and Debug** and **xRTOS** in the activity bar as needed
during the session.

.. figure::  readme_images/openairext_full_debug_view.png
     :align: center

.. raw:: html

   <br><br>

.. note::
   Always flash the same build you generate the launch configuration from.
   If you rebuild or change Thread Monitor settings, re-flash before starting
   a new debug session so the target matches the ELF.