Astra MCU SDK - VS Code Extension User Guide

Throughout this guide, <sdk-root> refers to the directory where you extracted or cloned the SDK.

Table of Contents

• Supported SoCs

• Prerequisites

• Install the Synaptics VS Code Extension

  • Uninstall old package and reinstall

• Install Tools

  • Tools checking

  • Tools installation

• Linux USB/serial permissions (recommended)

• Import Application/Example and Set SRSDK_DIR

• Imported Example

  • Build and Deploy

• Logger

• Memory Analyzer

• SR110 Debugging UI

• Video Streamer

• Register Info Data Base

Supported SoCs

This extension supports multiple SoC families. The core workflows (installation, tools, SDK import, logging, and memory analysis) are common across all devices.

For SoC-specific features such as build configurations, image generation, flashing, and debugging, refer to the appropriate platform-specific guide:

• SR110: See SR110 Build and Flash with VS Code

• SL2610: See SL2610 Build and Flash with VS Code

Throughout this guide, sections marked with 🔧 indicate SoC-specific functionality—consult your device’s platform guide for detailed instructions.

Prerequisites

• Supported host OS: Windows x64, Linux x86_64 or aarch64 (Ubuntu 22.04), macOS x86_64 or ARM64.

  • Note: For SL2610 development only Linux hosts are supported (WSL with Ubuntu 22.04 is supported). See Astra MCU SDK - WSL User Guide.

  • Windows users are strongly encouraged to use WSL2. See the VS Code WSL guide and the Astra MCU SDK - WSL User Guide.

• Visual Studio Code installed.

Install the Synaptics VS Code Extension

1. Click the Extensions icon on the side bar, click the three dots at the top right of the extensions window, and select Install from VSIX…

2. Locate the VSIX package in tools/ (for example, Astra_MCU_SDK_vscode_extension-<version>.vsix), and click Install.

3. Confirm the Synaptics extension appears in the VS Code activity bar.

4. Close and then reopen VS Code.

Uninstall old package and reinstall

1. Remove the currently imported Example directory from the workspace using the Remove from workspace option.

2. Uninstall the current extension using the Uninstall button.

3. Close any active Webview or reload the window.

4. Install the new extension VSIX package using the steps above.

Install Tools

Purpose: Check and install the necessary tools for build, image generation, flashing, and debugging.

Tools checking

Steps:

1. Open the Synaptics extension sidebar and select Install Tools.

2. The tool check runs automatically when the panel opens.

3. You can click Check tool status to re-run it at any time. A loader shows progress.

Note: On Linux and macOS, jq is required to read and write settings.json. If it is not installed, a terminal will open and prompt for your password. Once installed, the tool check continues automatically.

Note: If you are updating from a older version of the extension please reinstall the required tools

Result:

1. If a tool is missing, its version does not match or a migration warning, an exclamation mark (⚠️) will be displayed, and the installation checkbox will be automatically selected.

2. If a tool is already installed with the correct version, a green checkmark (✅) will appear, and the installation checkbox will remain unselected.

   

Tools installation

Steps:

1. After the tools check, choose an install directory or use the default:

   • Windows: C:/Users/<username>/SRSDK_Build_tools

   • Linux: /home/<username>/SRSDK_Build_tools

   • macOS: /Users/<username>/SRSDK_Build_tools

2. Click Install. The install script runs in the Install Script Terminal with progress shown in the UI.

Note:

• On Linux and macOS, you may be prompted for your password in the Install Script Terminal.

Note for AC6:

• Arm Compiler 6 requires manual installation due to licensing constraints. Follow the steps shown in the Tools Installer webview.

After installation: close and reopen VS Code.

VS Code extensions installed by the tools installer:

• C/C++ (Microsoft) for IntelliSense and debugging

• Serial Monitor

• MemoryView

• Memory Inspector CDT

Linux USB/serial permissions (recommended)

On Linux, add your user to the dialout group so the flashing tools can access USB CDC/UART devices:

sudo usermod -aG dialout $USER

Log out and log back in (or reboot) for the group change to take effect.

Import Application/Example and Set SRSDK_DIR

Purpose: Import the SDK <sdk-root>/examples/ directory into the VS Code workspace, either from a local folder or by cloning a repo.

Steps:

1. Click on the “Import Application/Example” button under the Quick Start Panel view.

2. This will open the web view to import SDKs example folder both from local and remote repositories.

3. Local Import: Under “LOCAL” tab, click on the “BROWSE” button and select the Astra MCU SDK’s example directory to import. This action will import the Astra MCU SDK and add it to the workspace.

   

4. Remote Import: Under the “REMOTE” tab, click on “CLONE REPO”, paste the repository URL to clone and then select the folder/location to clone into. GitLab needs proper SSH key setup. Cloning large repositories will take time. After cloning, the repository will be imported and added to the workspace in the “Imported Example”.
   
   

5. Once the Astra MCU SDK is added to the workspace, tool paths will be set in the settings.json. If settings.json doesn’t exist, it will be created; if it does, it will be modified accordingly.

6. After importing the examples, set SRSDK_DIR to <sdk-root> using Import SDK (see below).

Note: The settings.json, which is updated during tools installation, is used to configure workspace-specific settings such as paths and environment variables needed for proper Astra MCU SDK integration and development.

Import SDK (Set SRSDK_DIR)

Purpose:

The Import SDK action is used to set the workspace SRSDK_DIR to the Astra MCU SDK root . It does not perform repository cloning or import example/application source code — those actions are handled by the Import Application/Example flow. The SRSDK_DIR setting lets the extension locate tools, SDK packages, and the top-level SDK layout for build, image conversion and flashing workflows.

What it does

• Writes or updates the workspace settings.json entry (for example SRSDK_DIR) so other extension panels can find the SDK automatically.

Steps — Set SRSDK_DIR

1. Open the Import SDK view from the Synaptics extension sidebar. (Which will be visible after importing an example directory.)

   

2. Click BROWSE and choose the Astra MCU SDK root directory.

3. Confirm the selection. The extension validates the folder and updates the workspace settings.json with SRSDK_DIR pointing to the chosen path.

   

4. Verify the Build and Deploy panels detect the SDK path. If SRSDK_DIR is not set, the Build Configurations section is disabled.

   

Imported Example

Purpose: Provides a quick interface for managing the imported Astra MCU SDK’s example folder and offers essential actions.

Options:

1. Refresh: Will reload the current workspace.

2. Build and Deploy: Provides a combined interface for building and flashing the image onto the device and for debugging.

3. View in Explorer: To open the current folder in explorer.

4. Remove from Workspace: To remove the currently imported folder from the workspace.

Note: Currently, only one Astra MCU SDK can be imported at a time. Importing multiple repos in same workspace is not supported yet. In Windows, the suggested path length of the imported SDK folder should not exceed 100 characters.

Build and Deploy

Purpose: Provides a unified environment to build, image generation, flashing and debugging.

Steps:

1. Once the required Astra MCU SDK is imported, within Imported Repos column, click on “Build and Deploy”. This will open the Build and Deploy Webview. Make sure you have imported the “examples” directory for building the custom applications.

2. Once you import the examples directory and open the Build and Deploy if you have not set the SRSDK_DIR through the Import SDK view you will not be able to build any application so please make sure you import the SDK if you want to continue with the build configuration step.

Workflow Description: The Build and Deploy webview is a unified interface for multiple operations. Users can perform either one operation at a time or combination of operations.

🔧 SoC-Specific Build & Deploy Workflows:

For detailed instructions on building, flashing, debugging, and other platform-specific features, refer to your SoC’s platform guide:

• SR110 users: See SR110 Build and Flash with VS Code

• SL2610 users: See SL2610 Build and Flash with VS Code

Common Workflow Principles:

Integrated workflow: This unified webview is used to manage SDK build, binary conversion, image flashing and debugging from a single interface. This provides users with two modes of operation:

a. Unified workflow – Users can configure all required options and execute the full workflow in one step. This will build the SDK, generate the binary, and flash it onto the device.

b. Isolated workflow – Users can perform individual steps independently, such as building only the .axf/.elf, generating a binary, flashing an existing binary or debugging.

Panels you will see (common layout):

• Build Configurations (select project, build type/mode, board, compiler, toolchain, and app).

• Image Generation and Image Flashing (when supported on your SoC).

• Debug Options (SR110 only).

The exact options within each panel are SoC-specific; follow the platform build-and-flash guides for details.

Logger

The ASTRA MCU Extension has a built in LOGGER tab to connect to the logger port and visualize the logs.

1. The logger utility is available in the default bottom panel of VS Code denoted as LOGGER.

2. Connect the logger port (UART/DAP logger), select the COM Port from the dropdown and click Connect. The logs will be displayed in the display area as shown below.

3. The logger now has utilities to save the ongoing log session and also load previously saved log files (which are in either .txt/.log format).

4. The logs are also color coded with respect to their log level, which would enhance the ease of use for the user.

• Green - LOG_LEVEL_INFO

• Red - LOG_LEVEL_ERROR

• Yellow - LOG_LEVEL_WARN

• White - LOG_LEVEL_DEBUG

5. Apart from this there is also a utility to filter out the logs based on the above mentioned log levels for easy filtering of relevant logs.

Memory Analyzer

Purpose:

The Memory Analyzer parses linker .map files and produces both summary and per-object analyses to help you understand flash and RAM usage. It is useful to find large symbols, inspect function-level code sizes, and generate reports for optimization.

What the analyzer reports:

• Total code size (flash): Sum of .text and related read-only sections.

• Total RW data (initialized RAM): Sum of .data sizes.

• Total ZI data (uninitialized RAM / .bss): Sum of .bss sizes.

• Total RAM usage: RW + ZI.

• Top consumers chart: Visual top-10 object files by total size (code + RW + ZI).

• Memory breakdown: Section-level view (Code, Const/ROData, RW, ZI) with simple Stack/Heap estimates shown in the UI.

• Detailed object analysis: Per-object cards showing codeSize, rwDataSize, ziDataSize, total size, and a list of discovered functions with individual sizes.

Pre-requisites:

• A linker .map file from a build (common location: examples/build/<target>/<compiler>/<target>.map).

Supported compilers & parsing behaviour:

• The analyzer understands GCC-style , AC6-style or LLVM-style map file layouts and exposes a Compiler selector (GCC/AC6/LLVM) in the UI. If the parser cannot find expected sections, the extension shows a warning and displays sample fallback data to demonstrate the UI.

How to use the UI:

1. Open the Memory Analyzer panel from the Synaptics extension sidebar.

2. Drag & drop a .map file into the upload area or use Browse to choose the file.

3. Select the compiler type in the dropdown (GCC/AC6/LLVM) and click Analyze Memory.

4. Wait for the loader; once complete the Memory Summary and Detailed Object Analysis panels appear.

5. Use the search box to filter objects/functions, change Sort by to reorder, and use pagination controls to navigate large result sets.

SR110 Debugging UI

🔧 SR110 only

This section covers SR110-specific debugging UI features available in the extension. For step-by-step setup and build/flash prerequisites, see SR110 Build and Flash with VS Code.

Download and Reset Program

Pre-requisites:

1. Install the following extensions using the “Astra SDK Tools Installer” tab:

   • C/C++ IntelliSense, debugging, and code browsing extension in VS Code.

   • MemoryView extension to view the memory map while debugging.

   • Serial Monitor extension for viewing logs while debugging.

   • Memory Inspector CDT extension by Eclipse IDE.

2. Import an Astra MCU SDK before debugging.

3. Ensure the debug probe and the target device are properly connected.

Steps:

1. In the Build and Deploy webview, select the Debug Options panel.

2. For a unified workflow, open Build Configurations, choose Debug under BuildType, and enable Debug Options.

   

3. In Debug Options, select the AXF/ELF path (auto-populated if a debug build completed).

4. Choose the probe, transport, and speed settings appropriate for your setup.

5. Choose a default or custom config file. Default config files are under tools/openocd/configs/.

   

6. Select a debug mode: Download and Reset Program, Attach to Running Program, or Attach and Halt Program.

   

7. Click Run to start debugging. OpenOCD and GDB will start in separate terminals.

8. Once connected, the debugger pauses at main.

   

9. Use the Debug sidebar to view variables, call stack, registers, and breakpoints.

   

Global Variables

Purpose: View global variables and values in a dedicated panel.

Steps:

1. Right-click in the editor and select Show Global Variables.

   

2. The panel lists global variables, addresses, types, and values. It refreshes when the debugger pauses.

   

Debug Toolbar

Once a debug session starts, the toolbar provides common controls.

Reset options:

Option	Description
Reset and Break at Symbol	Reset and stop at a specific symbol you enter.
Reset and Halt	Reset and halt at Reset_Handler.
Reset and Run	Reset and run without stopping.

Other options:

• Continue/Pause: Continue or pause execution. On Linux/macOS, use the custom pause button if needed.

  

• Step Over, Step Into, Step Out

• Restart: Restart debug session at the same entry point.

• Stop: End the debug session.

Memory Inspection and Manipulation

1. Right-click a variable and select View Binary Data to open a memory view.

   

2. Right-click in the editor and select Open Memory Viewer for a split view with edit/fill controls.

   

3. The left panel supports multiple formats, periodic refresh, and configurable display.

   

4. The right panel supports Memory Edit and Memory Fill operations.

Note: The fill value must fit the selected width. If shorter, it is padded with zeros.

Disassembly Viewer

Purpose: View disassembly with navigation tools.

1. Right-click in the editor and select Open Advanced Disassembly Viewer.

   

2. Use the advanced panel to jump to addresses, go to PC, or navigate history.

   

Logging (while debugging)

• To redirect logs to the OpenOCD terminal:

  • Edit Configs → COMPONENTS CONFIGURATION → Utilities → LOGGER_DEFAULT_INTERFACE.

  • Select LOGGER_IF_CONSOLE or LOGGER_IF_UART_1_CONSOLE, save, and rebuild in Debug mode.

  

• To view logs via DAP logger port:

  • Ensure Serial Monitor extension is installed.

  • Start a debug session, select the DAP logger port in Serial Monitor, and click Start Monitoring.

  

Attach to Running Program

Follow the configuration steps above, then select Attach to Running Program as the debug mode. This attaches to an already running binary and allows pause/inspect.

Attach and Halt Program

Follow the configuration steps above, then select Attach and Halt Program to attach and pause immediately.

Video Streamer

🔧 SR110 only

Purpose: Stream video output frames while a vision use case is running.

Pre-requisites:

• Install Python and required packages via the Astra SDK Tools Installer.

• Flash the vision use case binary and ensure the device is connected.

Steps for vision use cases:

1. Source options:

   • RGB: display frames in RGB (unchecked = grayscale).

   • Demosaic: select demosaic type from the dropdown.

2. Overlay options: Toggle FPS and Resolution overlays.

3. Recording options:

   • Record Frames: save raw and overlayed frames.

   • Record Video: save frames as video.

   • Recording FPS: control saved video frame rate.

   • Output location:

     • Windows: C:/Users/<username>/video_stream_output

     • Linux: /home/<username>/video_stream_output

     • macOS: /Users/<username>/video_stream_output

4. Usecase Dynamic Commands:

   • Select the CDC port, choose UC ID, and click Create Use Case.

   • Use Send command for custom commands if needed.

5. Click Start Use Case to begin streaming (video pops up).

6. Use Stop Use Case to stop; Resume Use Case to restart.

Recovery if streamer freezes:

• Close the video window, click Stop Use Case, press Reset, and try again.

Hand Gesture Detection use case:

1. Select Hand Gesture Detection in UC ID, then Create Use Case and Start Use Case.

2. Switch visualization modes (720p, 320x320, Text only).

3. Adjust exposure/gain sliders as needed.

4. If upgrading from older extension versions, reinstall Python packages (new modules are used).

Note: For non-auto-run use cases, Create Use Case + Start Use Case is sufficient. Connect Image Source is for auto-run use cases.

Doorbell use case (auto-run):

• Does not require Create or Start Use Case.

• Open LOGGER tab, select the logger port, and click Connect.

• Press Application chip RESET to start streaming.

• Output location:

  • Windows: C:/Users/<username>/video_stream_output

  • Linux: /home/<username>/video_stream_output

  • macOS: /Users/<username>/video_stream_output

Wakeup triggers:

• Timer (CONFIG_WAKEUP_TRIGGER = 1): wakes every 10 seconds.

• GPIO (CONFIG_WAKEUP_TRIGGER = 2): connect GND, wait 10 seconds after hibernation, then connect UART0 RX to trigger wake-up.

Auto-run use cases:

1. Select UC ID and click Connect Image Source.

2. The video stream appears automatically.

Register Info Data Base

🔧 SR110 only

The Register Info Data Base view provides a searchable database of SoC/peripheral registers, bitfields, and addresses for quick reference.

Steps to use:

1. Open the Register Info Data Base view from the Synaptics extension sidebar.

2. Use the search box to find registers by name, address, or description.

What it provides:

• Register name, address, size, reset value, description, and bitfield breakdown.

• Bitfield details (bit ranges, access type, and notes).

• Quick-copy buttons to copy addresses or register names.

• Export current search results to CSV.

Tips:

1. Search by full name (GPIO_CTRL), partial name (GPIO), address (0x40100000), or description keyword (enable, irq).

2. Use filters to limit results by peripheral, access type (R/W/RW), or address range.

---