Astra MCU SDK Reference

This document is a comprehensive reference for the Astra MCU SDK. It describes the SDK structure, build and configuration model, project layout, image generation, flashing tools, and common troubleshooting. It is not a quick start guide and focuses on SDK internals and CLI workflows.

Throughout this guide, <sdk-root> refers to the folder where you extracted or cloned the SDK (for example, C:\Users\<YourName>\ASTRA_MCU_SDK_x.x.x\).

Table of Contents

Scope and Audience

Use this reference if you need to:

  • Understand how the SDK is organized and built.

  • Configure SDK or application features.

  • Build SDK packages and applications with the CLI.

  • Generate images and flash devices.

  • Troubleshoot build, image generation, or flashing issues.

Before using this reference, complete the setup and installation steps:

Supported Platforms and Boards

Boards

  • Astra Machina Micro SR110 (SR110_RDK)

  • Astra Machina SL2610 (SL2610_RDK)

Platform Differences (at a glance)

Feature

SR110

SL2610

MCU core

Cortex-M55

Cortex-M52

NPU

Ethos-U55

None

Flash media

External XSPI

eMMC (via USB boot tool)

Image generation

SRSDK image generator

Image generator + USB boot tool

Debug

OpenOCD + probe

Not supported in this SDK flow

Toolchains

GCC, AC6, LLVM

GCC, AC6

Platform Guides

Host Requirements

Supported Host OS

  • Windows (x64)

  • Linux (Ubuntu 22.04)

  • macOS (Apple Silicon & Intel)

Required Tools

Tool

Version Guidance

Notes

CMake

4.1.2

Build system generator

Ninja

1.13.1

Build executor

Python

3.13.x

Required for configuration tools and image generation

OpenOCD

Host package or xPack

Required for SR110 flashing

Toolchains

  • GCC 13.2.1 (all platforms)

  • Arm Compiler 6.19 (AC6)

  • LLVM Clang 21.x (SR110 only; requires GCC sysroot)

Use only one toolchain per build. Do not mix toolchains across SDK and application builds.

Environment Setup

Use these for host setup and tool installation:

SDK Repository Layout

Top-level directories:

  • arch/ CPU architecture support

  • board/ Board-specific support files

  • bootloader/ Bootloader sources

  • configs/ SDK defconfigs (bootloader, tflite, default package)

  • drivers/ Hardware drivers

  • examples/ Sample applications and example build system

  • kconfig/ SDK-level configuration entry

  • os/ RTOS support (FreeRTOS and related)

  • soc/ SoC-specific sources

  • tools/ Build, image, flashing, and utility tools

  • utilities/ Common utilities

  • third_party/ External dependencies

Examples Layout (in-tree)

examples/
|-- README.md                    # Examples overview and build guidance
|-- audio_examples/              # Audio examples
|   `-- <example>/               # Example application
|-- driver_examples/             # Driver examples
|   |-- <example>/               # Example application
|   |   |-- configs/             # Application defconfigs
|   |   |-- hw/<BOARD>/          # Board-specific init files
|   |   |-- CMakeLists.txt       # Application CMake entry
|   |   |-- Makefile             # Application build wrapper
|   |   |-- kconfig              # Application config options
|   |   |-- src.cmake            # Application source list
|   |   `-- <sources>            # Application source files
|-- inference_examples/          # Inference examples
|   `-- <example>/               # Example application
|-- sample_demo_app/             # Standalone demo application
|-- system_manager/              # Standalone system manager application
|-- usb_examples/                # USB examples
|   `-- <example>/               # Example application
`-- vision_examples/             # Vision examples
    `-- <example>/               # Example application

Out-of-tree custom applications are supported. Point SRSDK_DIR to the SDK root and keep your application repo separate.

The current in-tree examples are organized by functional category. Within each application, the configs/ directory holds that app’s defconfigs for all supported boards, while the hw/<BOARD>/ directory contains board-specific hardware setup needed by that app, such as pinmux, UART, and logger mux configuration.

Project Structure and Module Organization

The SDK is organized as functional modules. Each module typically contains its own CMakeLists.txt and, when configurable, a Kconfig file. The root CMakeLists.txt includes major subsystems, and each subsystem adds its sources and include paths.

Root-Level Build Entry

  • CMakeLists.txt in the SDK root drives inclusion of core subsystems (bootloader, firmware, tflite, drivers, OS).

  • tools/cmake/flags.cmake centralizes compiler flags and warnings.

  • tools/cmake/ contains SDK CMake modules and shared example-build helper modules.

Module-Level Structure

  • Each module uses target_sources() to add sources and target_include_directories() to expose headers.

  • Modules can be conditionally included based on Kconfig selections.

Kconfig Hierarchy

  • Top-level kconfig sources module Kconfig files (e.g., drivers/Kconfig, soc/*/Kconfig).

  • Selecting options in Kconfig controls which modules and features are built.

Where to Look for Specific Pieces

  • SoC configuration: soc/

  • Board configuration: board/

  • Drivers: drivers/

  • OS abstraction: os/

  • Bootloader: bootloader/

  • TFLite Micro: AI/ and third_party/

  • Tools and scripts: tools/

  • App/Example inclusion logic: category-level files such as examples/inference_examples/CMakeLists.txt and per-app files such as examples/<example_type>/<app>/CMakeLists.txt

Build System Overview

The SDK supports two primary build entry points:

  • SDK root (<sdk-root>): build the SDK package, bootloader, or TFLite Micro libraries.

  • Application folder (<sdk-root>/examples/<example_type>/<app> or examples/<app>): build an individual application, either app-only or combined SDK + app.

Out-of-tree builds are supported: keep your custom application in a separate folder and set SRSDK_DIR to the SDK root.

The build system is layered:

  • Make: orchestration and entry points (Makefile in the SDK root and in each application directory under examples/).

  • Kconfig: configuration UI and .config generation.

  • CMake: build generation.

  • Ninja: actual compilation and linking.

Key Build Concepts

  • Defconfig: Minimal config snapshot. Applied to produce .config.

  • .config: Full configuration file, used to generate config.h and build flags.

  • config.h: Generated header consumed by C/C++ sources.

  • SDK package: Installed libraries and headers used by application builds.

  • SDK package installation: Produces a reusable SDK package (headers, libraries, toolchain CMake files, and config.h) that application builds link against.

CMake Build Details

This section describes the CMake flow at a practical level.

SDK Root CMake (core SDK builds)

  • Reads build/config.h to load CONFIG_* settings (generated from Kconfig).

  • Uses those settings to select linker scripts and build flags.

  • Builds the SDK libraries and packages them for reuse.

  • Exports a CMake package under install/<BOARD>/<BUILD_TYPE>/lib/cmake/SynapticsSDK/.

Examples CMake (application builds)

  • Builds app targets named ${CONFIG_PROJECT}_${CONFIG_BUILD_TYPE} (for example sr110_cm55_fw).

  • BUILD=SRSDK builds the SDK package and the app together.

  • BUILD=EXAMPLE uses the app-local SDK install under that application’s install/ directory. This requires that the application’s SDK package has already been created at least once, typically by an earlier combined SDK+app build.

  • BUILD=EXAMPLE USE_PREINSTALLED_SDK=1 uses the SDK package already installed under SRSDK_DIR/install/<BOARD>/<BUILD_TYPE>/, typically created earlier from the SDK root for the selected board and build type.

  • Some applications need SDK dependencies beyond what is included in the default installed SDK package. In that case, the build system automatically falls back to building an app-specific SDK package locally and then builds the application against that package.

  • Example apps are included when their kconfig symbol is enabled.

  • USE_APP_CACHE=ON (default) uses a small per‑app cache of SDK headers/libs for faster rebuilds.

Configuration Model (Kconfig)

Where Configuration Lives

  • SDK defconfigs: configs/<BOARD>/*_defconfig

  • Application defconfigs: examples/**/configs/*_defconfig

Configuration Flow

  1. Apply a defconfig to generate .config.

  2. (Optional) Modify using menuconfig.

  3. Build generates config.h and uses it for compilation.

The Makefiles use Python helpers under tools/scripts/kconfig/:

  • defconfig.py applies defconfigs.

  • menuconfig.py launches the interactive menu.

  • genconfig.py generates config.h.

  • savedefconfig.py writes a minimal defconfig.

Key Defconfig Fields

Common fields you will see in defconfigs:

  • CONFIG_PROJECT: Project family (e.g., sr110, sl2610).

  • CONFIG_BUILD_TYPE: Target type (e.g., cm55_fw, cm52_fw, bootloader, tflite_micro).

  • CONFIG_COMPILER: Compiler selection (gcc, ac6, llvm).

  • CONFIG_TOOLCHAIN : Toolchain selection (GCC.13.2.1, AC6.6.18.0, LLVM)

  • CONFIG_BOARD: Board name (e.g., sr110_rdk, sl2610_rdk).

  • CONFIG_BOARD_REV: Board revision (when applicable).

  • CONFIG_CPU_LIST: CPUs included in a multi-CPU board build (for example CM55 CM4).

  • CONFIG_BUILD_LIST: Multi-CPU build entries processed by make astrasdk (for example cm55_fw cm55_bootloader_fw cm4_fw).

These values drive the build directory structure and output names. CONFIG_COMPILER must match the active toolchain environment variables; use the same compiler for SDK and app builds. If CONFIG_BUILD_LIST is defined in the active SDK defconfig, the SDK root build runs in multi-CPU mode and builds each listed firmware entry in sequence.

Build Modes

CONFIG_BUILD_MODE controls optimization and output directories:

  • release: optimized output, minimal logging.

  • debug: debug symbols and extra logging.

Build modes map to output folders: release/ or debug/.

Note: Build types used in defconfigs are cm55_fw, cm52_fw, bootloader, and tflite_micro.

Build Workflows

SDK Root Builds (from <sdk-root>)

Use SDK root for bootloader, TFLite Micro, or SDK package builds.

  1. Apply a defconfig:

make default_config BOARD=<BOARD>

  1. Build the currently selected SDK target:

make astrasdk

  1. For bootloader or TFLite Micro builds, apply the corresponding defconfig and then run:

make <bootloader_defconfig> BOARD=<BOARD>
make astrasdk

make <tflite_defconfig> BOARD=<BOARD>
make astrasdk

Multi-CPU SDK Workflow

Use this SDK-root flow when one board build must produce firmware for more than one CPU. The main difference from a single-CPU SDK build is that you apply a board-level main defconfig that defines the CPU list and the firmware entries to build.

For the current SR110 multi-CPU flow:

cd <sdk-root>
make sr110_rdk_main_defconfig BOARD=SR110_RDK
make astrasdk

The main defconfig lives under configs/<BOARD>/ and defines the overall build plan. Example:

CONFIG_PROJECT="sr110"
CONFIG_BOARD="sr110_rdk"
CONFIG_CPU_LIST="CM55 CM4"
CONFIG_BUILD_LIST="cm55_fw cm55_bootloader_fw cm55_tflite_micro_fw cm4_fw"
CONFIG_BUILD_MODE="release"

How the workflow runs:

  1. make sr110_rdk_main_defconfig BOARD=SR110_RDK selects the board-level multi-CPU build definition.

  2. make astrasdk reads CONFIG_BUILD_LIST and treats each entry as a separate SDK build target.

  3. For each entry, the build system merges the main defconfig with the matching CPU-specific defconfig from configs/<BOARD>/, generates build/config.h, and runs CMake + Ninja for that target.

  4. Installable entries produce reusable SDK package outputs that later application builds can link against.

Common CONFIG_BUILD_LIST entry patterns:

Entry Pattern

Meaning

Installed by make astrasdk

<cpu>_fw

Standard firmware

Yes

<cpu>_secure_fw

TrustZone secure firmware

Yes

<cpu>_nonsecure_fw

TrustZone non-secure firmware

Yes

<cpu>_bootloader_fw

Bootloader packaged in SDK-install flow

Yes

<cpu>_downloader_fw

Downloader packaged in SDK-install flow

Yes

<cpu>_bootloader

Bootloader-only build output

No

<cpu>_downloader

Downloader-only build output

No

<cpu>_tflite_micro_fw

TFLite Micro build flow

No

Defconfig naming follows the entry type. Examples:

  • cm55_fw expects sr110_cm55_fw_defconfig

  • cm55_bootloader_fw expects sr110_cm55_bootloader_fw_defconfig

  • cm55_tflite_micro_fw expects sr110_cm55_tflite_micro_defconfig

  • cm4_fw expects sr110_cm4_fw_defconfig

This layout also supports master-slave CPU designs. In those cases, keep shared resource ownership such as clock and pinmux on the master CPU and use the slave CPU defconfig to enable only the modules and drivers that CPU actually needs.

After the SDK multi-CPU build completes, application builds remain per application and per target CPU. Build each application from its own directory using the app defconfig for the CPU you want, and reuse the installed SDK package with BUILD=EXAMPLE or USE_PREINSTALLED_SDK=1 as needed.

Application Builds (from an application directory under examples/)

Use an individual application directory such as <sdk-root>/examples/<example_type>/<app> or <sdk-root>/examples/<app> to build that application.

The configs/ directory contains the defconfigs supported by that application.

Path tips: Use absolute paths for SRSDK_DIR and toolchain variables. On Windows, use escaped backslashes or forward slashes.

Combined SDK + App build

export SRSDK_DIR=<sdk-root>
make <app_defconfig> BUILD=SRSDK

App-only build (uses installed SDK package)

export SRSDK_DIR=<sdk-root>
make build

BUILD Mode (Application only)

  • BUILD=EXAMPLE (default): build the app only using the app-local SDK package under that application’s install/ directory. This package must already exist from an earlier SDK+app build.

  • BUILD=SRSDK: build SDK package and the app in one flow (requires SRSDK_DIR).

  • BUILD=NONE: apply defconfig only (no build).

When to use:

  • Use BUILD=SRSDK for the first build, after SDK source changes, or when switching toolchains.

  • Use BUILD=EXAMPLE for faster iteration when only app code changes and the application’s local SDK package already exists.

Custom Tools Override for Application Builds

By default, application builds use the SDK’s shared tools from:

<sdk-root>/tools/

The application build wrapper resolves this as:

  • TOOLS_DIR=$(SRSDK_DIR)/tools when USE_CUSTOM_TOOLS=0 (default)

  • TOOLS_DIR=<app-dir>/tools when USE_CUSTOM_TOOLS=1

Use this when an application repository needs to carry its own copy of the application build helpers instead of using the SDK copy.

Example:

cd <sdk-root>/examples/<example_type>/<app>
export SRSDK_DIR=<sdk-root>
make <app_defconfig> BUILD=SRSDK USE_CUSTOM_TOOLS=1

The same override can also be used with other app-side flows such as:

make <app_defconfig> BUILD=NONE USE_CUSTOM_TOOLS=1
make build USE_CUSTOM_TOOLS=1
make imagegen USE_CUSTOM_TOOLS=1

What USE_CUSTOM_TOOLS=1 changes

The application wrapper and app CMake look for these helper paths under <app-dir>/tools/ instead of <sdk-root>/tools/:

  • cmake/ParseConfigHeader.cmake

  • cmake/example_config_setup.cmake

  • cmake/case_handler.cmake

  • cmake/example_target_detector.cmake

  • cmake/toolchain.cmake

  • cmake/example_flags.cmake

  • cmake/get_git_info.cmake

  • cmake/example_build_config.cmake

  • cmake/toolchain_setup.cmake

  • cmake/example_linker_setup.cmake

  • scripts/kconfig/defconfig.py

  • scripts/kconfig/menuconfig.py

  • scripts/kconfig/genconfig.py

  • scripts/kconfig/savedefconfig.py

  • scripts/sdk_rebuild.py

  • image_gen/image_generator.py

  • scripts/image/build_preboot_mcu.py

  • scripts/image/build_preboot_mcu_wsl.py

If you keep custom tools inside the application repository, preserve the same directory layout and filenames so the existing application Makefile and CMakeLists.txt continue to work unchanged.

Note:

  • SRSDK_DIR is still required even when USE_CUSTOM_TOOLS=1.

  • The application wrapper itself is still included from $(SRSDK_DIR)/tools/make/example_app.mk.

  • During BUILD=SRSDK, the compiler toolchain file ${CONFIG_TOOLCHAIN}.cmake is still included from $(SRSDK_DIR)/tools/cmake/.

  • During BUILD=EXAMPLE, the toolchain file is loaded from the selected installed SDK package under install/<BOARD>/<BUILD_TYPE>/tools/cmake/.

Build Multiple Applications with One SDK Package

If you want to build several applications against the same SDK package, first build and install the SDK from the SDK root, then build each application with BUILD=EXAMPLE USE_PREINSTALLED_SDK=1.

cd <sdk-root>
export SRSDK_DIR=<sdk-root>
make default_config BOARD=<BOARD>
make astrasdk

cd <sdk-root>/examples/<example_type>/<app1>
make <app1>_defconfig BUILD=EXAMPLE USE_PREINSTALLED_SDK=1

cd <sdk-root>/examples/<example_type>/<app2>
make <app2>_defconfig BUILD=EXAMPLE USE_PREINSTALLED_SDK=1

This reuses the SDK package from SRSDK_DIR/install/<BOARD>/<BUILD_TYPE>/. If that package does not include the SDK pieces required by a specific application, the build system automatically creates an app-local SDK package for that application and continues the build.

Create a Custom Defconfig (Application)

  1. Start from an existing defconfig:

    make <app>_defconfig BUILD=NONE

  2. Open the configuration UI:

    make menuconfig

  3. Save your new defconfig under configs/ (for example my_custom_app_defconfig).

    make savedefconfig OUT=my_custom_app

    This writes configs/my_custom_app_defconfig in the current application directory.

The new defconfig can then be used like any other:

make my_custom_app_defconfig BUILD=SRSDK

Build Outputs and Artifacts

SDK Root Outputs

  • build/ contains build artifacts and config.h (CMake build tree is build/<project>/<compiler>/).

  • out/<target>/<mode>/ contains SDK root binaries:

    • GCC/LLVM: <target>.elf and <target>.bin

    • AC6: <target>.axf and <target>.bin

  • prebuilt/<PROJECT>/tflite_micro/<mode>/ contains TFLM libs when building tflite_micro.

For multi-CPU SDK builds, you get one output target per CONFIG_BUILD_LIST entry, for example out/sr110_cm55_fw/release/ and out/sr110_cm4_fw/release/.

Application Outputs

  • <app-dir>/out/<target>/<mode>/ contains application binaries.

    • GCC/LLVM: <target>.elf and <target>.bin

    • AC6: <target>.axf and <target>.bin

  • <app-dir>/build/<project>/<compiler>/ contains the application CMake build tree.

  • <app-dir>/build/<project>/<compiler>/srsdk_build/.cache/ is the app-local SDK cache (auto-managed; refreshed when SDK content changes). Disable with USE_APP_CACHE=OFF if needed.

  • <app-dir>/install/<BOARD>/<BUILD_TYPE>/ contains the app-local installed SDK package:

    • include/ SDK headers

    • lib/ SDK libraries

    • config.h

    • tools/cmake/ SDK CMake toolchain modules used by the app build

The installed package also provides CMake package files under:

  • App-local install, generated during BUILD=SRSDK for an application:

<app-dir>/install/<BOARD>/<BUILD_TYPE>/lib/cmake/SynapticsSDK/

  • SDK-root install, generated from <sdk-root> after make default_config BOARD=<BOARD> and make astrasdk:

<sdk-root>/install/<BOARD>/<BUILD_TYPE>/lib/cmake/SynapticsSDK/

Generated Config Headers

  • build/config.h in SDK root: generated from SDK .config.

  • build/config.h in an application directory: generated from that application’s .config and used for the application build.

Target naming:

  • <target> is ${CONFIG_PROJECT}_${CONFIG_BUILD_TYPE} (for example sr110_cm55_fw or sl2610_cm52_fw).

  • <mode> is release or debug, based on CONFIG_BUILD_MODE.

Image Generation

SR110 Image Generation (SRSDK Image Generator)

Tool: tools/srsdk_image_generator/srsdk_image_generator.py

Required: Python 3.13 venv active and tools/srsdk_image_generator/requirements.txt installed.

Typical command (from <sdk-root>/tools/srsdk_image_generator):

cd <sdk-root>/tools/srsdk_image_generator
python srsdk_image_generator.py \
  -B0 \
  -flash_image \
  -sdk_secured \
  -spk "<sdk-root>/tools/srsdk_image_generator/Inputs/spk_rc4_1_0_secure_otpk.bin" \
  -apbl "<sdk-root>/tools/srsdk_image_generator/Inputs/sr100_b0_bootloader_ver_0x012F_ASIC.axf" \
  -m55_image "<sdk-root>/examples/<example_type>/<app>/out/sr110_cm55_fw/release/sr110_cm55_fw.elf" \
  -flash_type "GD25LE128" \
  -flash_freq "67"

Output (example):

<sdk-root>/tools/srsdk_image_generator/Output/B0_Flash/B0_flash_full_image_GD25LE128_67Mhz_secured.bin

Key flags:

  • -flash_image or -host_image: choose flash or host image output.

  • -sdk_secured / -sdk_non_secured: SDK security mode.

  • -model_secured / -model_non_secured: model security mode.

  • -spk, -apbl, -m55_image: required inputs for SR110.

  • -flash_type, -flash_freq: flash configuration (types: GD25LE128, W25Q128, MX25U128; frequencies: 34, 67, 100, 134 MHz).

  • -m4_image, -npu_c_image, -model: additional payloads for multi-core or model flows.

  • -single_slot: generate a single-slot image layout.

  • -json_attr / -parse_attr: use JSON-based flash attributes.

  • -Q4: flash 4-bit support (1/0).

SL2610 Image Generation (Image Generator)

Tool: tools/image_gen/image_generator.py

Required: Python 3.13 venv active.

Note: SL2610 image generation is not supported on native Windows. Windows users should use WSL for image generation. In the WSL environment, install required tools such as Python, make, and the Arm GNU toolchain. You can use the VS Code extension’s Tools Installer from WSL, or follow Linux Environment guide for CLI setup.

Recommended entry:

cd <sdk-root>/examples/<app-dir>
make imagegen

This runs a two-step pipeline:

  • tools/image_gen/image_generator.py to generate raw images using tools/image_gen/inp.json.

  • tools/scripts/image/build_preboot_mcu.py to package sub-images for USB boot and eMMC workflows.

Final outputs:

  • <app-dir>/out/image/eMMCimg/sysmgr.subimg.gz

  • <app-dir>/out/image/eMMCimg/

  • <app-dir>/out/image/usb_boot/

Intermediate outputs from image generation:

  • <app-dir>/out/nexus_bin/

  • <app-dir>/out/nexus_loadable/

If you need to change inputs, update tools/image_gen/inp.json. Paths in this file are relative to the application’s out/ directory. The preboot packaging step uses signing keys under tools/signingKeys/<soc>/ and SPK assets for USB boot images.

If you see permission errors on Linux/macOS:

cd <sdk-root>
chmod +x tools/scripts/image/bin/gen*

Flashing

SR110 (OpenOCD Flash Script)

Tool: tools/openocd/scripts/flash_xspi_tcl.py OpenOCD config files live under tools/openocd/configs/. For SR110, sr110_m55.cfg is the standard config.

Example (from <sdk-root>):

cd <sdk-root>
python tools/openocd/scripts/flash_xspi_tcl.py \
  --cfg_path tools/openocd/configs/sr110_m55.cfg \
  --image tools/srsdk_image_generator/Output/B0_Flash/B0_flash_full_image_GD25LE128_67Mhz_secured.bin \
  --erase-all

Key options:

  • --cfg_path (required): OpenOCD config file

  • --image: Binary image to program

  • --erase-all: Full chip erase

  • --verify-only: Verify contents without programming

  • --probe: Select probe (default cmsis-dap, use jlink for J-Link)

  • --openocd: Path to OpenOCD binary

  • --flash-offset: Flash offset for programming

  • --file-offset: Offset into image file

  • --erase-only: Erase only, no programming

  • --log-level: DEBUG/INFO/WARN/ERROR

  • --tcl_port, --tcl_host: OpenOCD TCL interface settings

  • Use --probe jlink (or --probe cmsis-dap) to select the adapter driver.

SL2610 (USB Boot Tool)

Tool: tools/usb_boot_python_tool/USB_BOOT_TOOL/usb_boot_tool.py

Required: Python 3.13 venv active and pyserial installed.

Enter USB boot mode first:

  • Press and hold USB_BOOT, then press RESET.

  • Release RESET, then release USB_BOOT.

Run System Manager (from <sdk-root>/tools/usb_boot_python_tool/USB_BOOT_TOOL):

cd <sdk-root>/tools/usb_boot_python_tool/USB_BOOT_TOOL
python usb_boot_tool.py --op run-sm \
  --sm <sdk-root>/examples/<example_type>/<app>/out/image/eMMCimg/sysmgr.subimg.gz \
  --spk <sdk-root>/examples/<example_type>/<app>/out/image/usb_boot/spk.bin \
  --keys <sdk-root>/examples/<example_type>/<app>/out/image/usb_boot/key.bin \
  --m52bl <sdk-root>/examples/<example_type>/<app>/out/image/usb_boot/m52bl.bin

Full eMMC flashing:

python usb_boot_tool.py --op emmc --img-dir <path-to-eMMCimg>

Notes:

  • --op emmc requires a Yocto-generated eMMCimg folder with emmc_part_list and emmc_image_list.

  • If run-sm fails because SM CDC is already running, power-cycle the board and retry.

Where to Run Commands

Use the table below to choose the correct working directory.

Command or Task

Run From

Notes

make default_config BOARD=<BOARD>

<sdk-root>

Applies SDK default defconfig

make <bootloader_defconfig> BOARD=<BOARD>

<sdk-root>

Apply SDK bootloader defconfig, then run make astrasdk

make <tflite_defconfig> BOARD=<BOARD>

<sdk-root>

Apply SDK TFLite Micro defconfig, then run make astrasdk

make astrasdk

<sdk-root>

Builds the currently selected SDK target

make <app_defconfig> BUILD=SRSDK

<sdk-root>/examples/<example_type>/<app> or <sdk-root>/examples/<app>

Combined SDK + app build

make build

<sdk-root>/examples/<example_type>/<app> or <sdk-root>/examples/<app>

App-only build (requires SRSDK_DIR)

make imagegen

<sdk-root>/examples/<example_type>/<app> or <sdk-root>/examples/<app>

Application image generation pipeline

srsdk_image_generator.py

<sdk-root>/tools/srsdk_image_generator

SR110 image generation

flash_xspi_tcl.py

<sdk-root>/tools/openocd/scripts

SR110 flashing (OpenOCD)

usb_boot_tool.py

<sdk-root>/tools/usb_boot_python_tool/USB_BOOT_TOOL

SL2610 USB boot flashing

Debugging

SL2610 - Manual Debug Steps (using OpenOCD and GDB)

This section outlines a manual, step-by-step workflow to load the bootloader and connect a debugger for the SL2610 device.

Prerequisites

  • OpenOCD installed and available in PATH

  • ARM GNU toolchain installed and available in PATH

  • SL2610 board with a J-Link connection

Applications (Modify or Create)

Modify an existing app

  • Update sources under examples/<example_type>/<app>/ or examples/<app>/.

  • If you change configuration options, re-run the app defconfig and rebuild:

cd <sdk-root>/examples/<example_type>/<app>
export SRSDK_DIR=<sdk-root>
make <app>_defconfig

Create a new app (minimal checklist)

  1. Create examples/<example_type>/<app>/ or examples/<app>/ for the new application.

  2. Add your application sources and headers.

  3. Add kconfig with a config symbol for the application.

  4. Add configs/<app>_defconfig entries for the supported board and build combinations.

  5. Add hw/<BOARD>/hw_init.c and hw_init.h if the application needs board-specific hardware setup such as pinmux, UART, logger muxing, or peripheral initialization.

  6. Add CMakeLists.txt, Makefile, and src.cmake following an existing application as a reference.

  7. Build from the application directory:

cd <sdk-root>/examples/<example_type>/<app>
export SRSDK_DIR=<sdk-root>
make <app>_defconfig BUILD=SRSDK
make <app>_defconfig

Minimal kconfig:

config <APP_SYMBOL>
    bool "Enable <app>"
    default y

Minimal CMakeLists.txt (pattern used by current applications):

cmake_minimum_required(VERSION 3.22)

if(DEFINED ENV{SRSDK_DIR})
    file(TO_CMAKE_PATH "$ENV{SRSDK_DIR}" SRSDK_DIR)
else()
    message(FATAL_ERROR "SRSDK_DIR is not set")
endif()

include(${TOOLS_DIR}/cmake/ParseConfigHeader.cmake)
include(${TOOLS_DIR}/cmake/example_config_setup.cmake)
setup_configs()

include(${TOOLS_DIR}/cmake/case_handler.cmake)
include(${TOOLS_DIR}/cmake/example_target_detector.cmake)
detect_target_config()

set(TARGET ${CONFIG_PROJECT}_${CONFIG_BUILD_TYPE})
string(TOUPPER ${CONFIG_BOARD} CONFIG_BOARD_UPPER)

include(${TOOLS_DIR}/cmake/toolchain.cmake)
include(${TOOLS_DIR}/cmake/example_flags.cmake)
include(${TOOLS_DIR}/cmake/example_build_config.cmake)
include(${TOOLS_DIR}/cmake/toolchain_setup.cmake)
setup_toolchain(${CONFIG_COMPILER})

if(${BUILD} STREQUAL "SRSDK")
    project(srsdk_lib LANGUAGES ASM C CXX)
    add_subdirectory("${SRSDK_DIR}" "${CMAKE_BINARY_DIR}/srsdk_build")
else()
    project(${TARGET} LANGUAGES ASM C CXX)

    find_package(SynapticsSDK 1.0 REQUIRED CONFIG
        PATHS "${INSTALL_ROOT}"
        NO_DEFAULT_PATH
    )

    include(${TOOLS_DIR}/cmake/example_linker_setup.cmake)
    setup_example_linker_scripts(${CONFIG_PROJECT} ${CONFIG_SYNA_CORE})

    add_executable(${TARGET})
    include(${CMAKE_SOURCE_DIR}/src.cmake)
endif()

Minimal src.cmake:

if(${BUILD} STREQUAL "EXAMPLE")
    target_sources(${TARGET} PRIVATE
        ${CMAKE_CURRENT_LIST_DIR}/<app>.c
        ${CMAKE_CURRENT_LIST_DIR}/main.c
        # Add hw_init.c when the app needs board-specific hardware setup
        ${CMAKE_CURRENT_LIST_DIR}/hw/${CONFIG_BOARD_UPPER}/hw_init.c
    )

    target_include_directories(${TARGET} PUBLIC
        ${CMAKE_CURRENT_LIST_DIR}
        # Add the board-specific include path when hw_init.h is used
        ${CMAKE_CURRENT_LIST_DIR}/hw/${CONFIG_BOARD_UPPER}
    )
else()
    target_include_directories(sdk_includes INTERFACE
        $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}/hw/${CONFIG_BOARD_UPPER}>
    )
endif()

Notes:

  • Follow the defconfig naming pattern used by existing applications for each supported board and core.

  • Add hw/<BOARD>/ for board-specific hardware setup such as pinmux, UART, or logger mux configuration.

Common mistakes:

  • Defconfig not found: confirm the file exists under the application’s configs/ directory and that BOARD matches the selected defconfig.

  • App not built: ensure CONFIG_<APP_SYMBOL>=y is set in the app defconfig.

  • App directory incomplete: ensure the app folder has kconfig, CMakeLists.txt, Makefile, and src.cmake.

  • Missing sources: ensure src.cmake and CMakeLists.txt include all required source files.

  • Wrong output target: check CONFIG_PROJECT and CONFIG_BUILD_TYPE.

Command Reference

SDK Root (<sdk-root>)

Command

Purpose

Result

make help

Show available targets

Prints target list

make list_defconfigs BOARD=<BOARD>

List SDK defconfigs

Console list

make default_config BOARD=<BOARD>

Apply default SDK defconfig

.config updated

make <name>_defconfig BOARD=<BOARD>

Apply specific SDK defconfig

.config updated

make menuconfig BOARD=<BOARD>

Edit SDK config

.config updated

make genconfig

Generate build/config.h

build/config.h created

make astrasdk

Build the currently selected SDK target

Use after make default_config BOARD=<BOARD> or make <name>_defconfig BOARD=<BOARD>; no additional BOARD= is needed when starting the build

make savedefconfig OUT=name BOARD=<BOARD>

Save minimal SDK defconfig

configs/<BOARD>/name_defconfig

make clean

Remove build artifacts

build/ cleaned

make cpp_check

Run cppcheck

Console output

Application Directory (<sdk-root>/examples/<example_type>/<app> or <sdk-root>/examples/<app>)

Command

Purpose

Result

make help

Show available targets

Prints target list

make list_defconfigs

List application defconfigs

Console list

make default_config

Apply the first defconfig in configs/ without building

.config updated

make <app>_defconfig BUILD=NONE

Apply an application defconfig only

.config updated

make <app>_defconfig BUILD=SRSDK

Build app-local SDK package and the application

SDK installed under the app and app built

make <app>_defconfig

Apply defconfig and build the application with BUILD=EXAMPLE

App built using the selected SDK package flow

make build

Build the application using the current .config

App binary updated in out/

make menuconfig

Edit application configuration

.config updated

make genconfig

Generate application build/config.h

build/config.h created

make imagegen

Generate application images

Image outputs created under the application directory

make savedefconfig OUT=name

Save minimal defconfig

configs/name_defconfig

make clean

Remove application build outputs

build/ and out/ cleaned

make clean_package

Remove the app-local installed SDK package

install/<BOARD>/ removed

make all

Alias for clean_package

App-local SDK package removed

Notes:

  • Application-side commands are run from the individual application directory, not from the examples/ root.

  • The selected defconfig provides CONFIG_BOARD, so BOARD= is not normally needed for application-side builds.

  • build_sdk, build_advanced, and build_all are internal helper targets typically invoked through the defconfig flow.

  • BUILD=NONE can be used to apply a defconfig without building.

  • USE_CUSTOM_TOOLS=1 switches application helper lookup from SRSDK_DIR/tools/ to <app-dir>/tools/.

Python Tools

Tool

Location

Purpose

srsdk_image_generator.py

tools/srsdk_image_generator/

SR110 image generation

image_generator.py

tools/image_gen/

SL2610 image generation

build_preboot_mcu.py

tools/scripts/image/

SL2610 sub-image packaging

flash_xspi_tcl.py

tools/openocd/scripts/

SR110 flashing (OpenOCD)

usb_boot_tool.py

tools/usb_boot_python_tool/USB_BOOT_TOOL/

SL2610 USB boot flashing

tools/scripts/kconfig/*

tools/scripts/kconfig/

Defconfig/menuconfig/genconfig helpers

Tools Overview (Non-VS Code)

  • tools/openocd/: OpenOCD configs and flashing scripts for SR110.

  • tools/usb_boot_python_tool/: USB boot flashing tool for SL2610.

  • tools/image_gen/: SL2610 image generator and inp.json configuration.

  • tools/srsdk_image_generator/: SR110 image generator and input examples.

  • tools/Inference/: Model conversion and inference helpers (see its README).

  • tools/JLink_Scripts/: J-Link scripts for debugging/programming.

  • tools/Debug_IC_FW/: Debug firmware support assets.

  • tools/signingKeys/: Signing keys used by SL2610 preboot packaging.

  • tools/SPK/: SPK assets used by secure image flows.

Note: Some tools have their own dependency requirements (for example tools/Inference/). Follow the tool-specific README when using them.

Troubleshooting

Build and Configuration Issues

  • SRSDK_DIR not set (application build fails)

    • Fix: export SRSDK_DIR=<sdk-root> before running application-side builds such as BUILD=SRSDK, BUILD=EXAMPLE, or menuconfig.

  • Build and Deploy button disabled in VS Code

    • Cause: An application/example directory is not imported or SRSDK_DIR is not set.

    • Fix: import the application/example, set SRSDK_DIR via Import SDK, then refresh the workspace (close and reopen VS Code).

  • App-only build fails because SDK package is missing

    • Fix: for app-local builds, run the application’s combined build once with make <app>_defconfig BUILD=SRSDK. If you want to use a preinstalled SDK package, build it first from <sdk-root> using make default_config BOARD=<BOARD> followed by make astrasdk.

  • Toolchain not found

    • Fix: ensure the correct toolchain env variable is set and the toolchain is on PATH.

    • Example: GCC_TOOLCHAIN_13_2_1=/opt/gcc-arm-none-eabi/bin.

  • LLVM build fails due to missing sysroot

    • Fix: set GCC_TOOLCHAIN_ROOT to the GCC toolchain root.

  • menuconfig fails on Linux

    • Fix: install libncurses5-dev and related packages per the Linux build_env guide.

  • defconfig not found

    • Fix: verify the defconfig file exists under the current application’s configs/ directory and that you are running the command from the correct application directory.

  • Custom tools override fails because helper scripts or CMake modules are missing

    • Fix: when using USE_CUSTOM_TOOLS=1, make sure the application repository contains the expected tools/ layout and filenames under tools/cmake/, tools/scripts/kconfig/, tools/scripts/, and tools/image_gen/.

  • Multi-CPU SDK build stops because one entry is missing a defconfig

    • Fix: check the active main defconfig under configs/<BOARD>/ and confirm every CONFIG_BUILD_LIST entry has a matching CPU-specific defconfig in the same board config directory.

  • config.h missing or stale

    • Fix: run make genconfig from the SDK root or from the application directory, depending on what you are building, or rerun the build to regenerate build/config.h.

  • TFLite Micro library not found

    • Fix: ensure prebuilt/<PROJECT>/tflite_micro/<mode>/ contains the library, or apply the appropriate TFLite Micro defconfig and rebuild from <sdk-root> using make astrasdk.

    • If NPU is enabled, TFLM library is required.

Python / Image Generation Issues

  • Python version mismatch

    • Fix: activate the SDK virtual environment and verify python --version is 3.13.x.

  • Missing Python packages

    • Fix: pip install -r tools/srsdk_image_generator/requirements.txt.

  • Imagegen permission errors (Linux/macOS)

    • Fix: chmod +x tools/scripts/image/bin/gen*.

Flashing Issues

  • OpenOCD not found

    • Fix: install OpenOCD and ensure it is in PATH.

  • OpenOCD cannot connect to target

    • Fix: check cable, power, and probe selection (--probe cmsis-dap or --probe jlink).

  • WSL USB device not visible

  • SL2610 USB boot fails

    • Fix: re-enter USB boot mode (USB_BOOT + RESET), then retry.

Build Output Issues

  • App builds but image generation fails

    • Fix: confirm output .elf exists under the application’s out/ directory and update image generator input paths.

  • App/Example build does not pick up new SDK headers/libs

    • Fix: clean the app cache (rm -rf <app-dir>/build/<target>/<compiler>/srsdk_build/.cache) or disable it by configuring with USE_APP_CACHE=OFF.

  • Link errors from mixed toolchains

    • Fix: ensure SDK and app are both built with the same compiler (GCC, AC6, or LLVM).