Getting started

neuralSPOT-X is Ambiq’s modular AI SDK. It assembles an application from your sources, reusable firmware modules and an AmbiqSuite HAL/BSP foundation. The nsx CLI takes you from an environment check through creating, building, flashing and inspecting that app.

Your project contains an editable CMakeLists.txt, an nsx.yml manifest and app-local module sources. Read How NSX builds on AmbiqSuite for the architecture, or follow the steps below to build your first app.

The lifecycle

One environment check, then five commands per app.

Command	What it does
nsx doctor	Checks the tools on your machine. Run it once after installing, and again whenever something breaks.
nsx create-app	Writes a new app directory targeting a board, and vendors its starter modules.
nsx configure	Resolves the module graph, writes nsx.lock, and generates the CMake build tree.
nsx build	Compiles and links the firmware image.
nsx flash	Builds if needed, then programs the board over SWD.
nsx view	Opens the SEGGER SWO viewer and streams output from the running firmware.

nsx doctor, nsx create-app, nsx configure and nsx build all work with no board attached. Flashing, viewing and resetting require a connected probe. nsx probes can run without one and reports an empty list.

What you need

NSX runs on macOS, Linux and Windows. The host tools below are what nsx doctor checks before it will call the environment healthy.

Requirement	Version	Why
Python	3.11 or newer	NSX is a Python package; this is its declared minimum.
uv	any	Used to manage Python environments, and checked by nsx doctor.
CMake	3.24 or newer	The generated app declares cmake_minimum_required(VERSION 3.24).
Ninja	any	The build backend NSX generates for.
Git	any	Module sources are fetched from their upstream repositories.
Arm GNU toolchain	any	The default cross compiler, arm-none-eabi-gcc.
SEGGER J-Link	any	Needed only by nsx flash, nsx view, nsx reset and nsx probes.

Two alternate compilers are optional and are reported only when they are present: Arm Compiler for Embedded (armclang) and Arm Toolchain for Embedded (ATfE). GCC builds every packaged example, so you do not need either to get started.

Work through it in this order

Step 1

Install the tools→

Set up Python, the NSX CLI, a toolchain and debugging tools for your operating system.

Step 2

Check your environment→

Run nsx doctor and resolve missing tools before creating an application.

Step 3

Create your first app→

Choose a board, scaffold the project and inspect the sources and modules NSX writes.

Step 4

Configure and build→

Resolve dependencies and compile a firmware image. This step needs no attached board.

Step 5

Flash, reset and view→

Connect your debug probe, program the board and inspect firmware output.

Step 6

Extend your application→

Add modules, explore examples and make the generated project your own.

Coming from legacy neuralSPOT? Read Migrating from neuralSPOT for how the old packages map onto NSX modules.

Notation

These placeholders are used throughout this section:

• <app-dir> is the directory of a generated or example app, whichever path you passed to nsx create-app or checked out.
• <board> is the board id from nsx.yml, for example apollo510_evb.

Command examples assume you are inside the app directory. NSX finds the nearest nsx.yml by walking up from the working directory, so --app-dir is only needed when you want to act on an app somewhere else.