# 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](https://ambiqai.github.io/neuralspotx/guides/modules/sdk-providers/)
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

- [Install the tools](https://ambiqai.github.io/neuralspotx/getting-started/install/): Set up Python, the NSX CLI, a toolchain and debugging tools for your operating system.
- [Check your environment](https://ambiqai.github.io/neuralspotx/getting-started/doctor/): Run nsx doctor and resolve missing tools before creating an application.
- [Create your first app](https://ambiqai.github.io/neuralspotx/getting-started/first-app/): Choose a board, scaffold the project and inspect the sources and modules NSX writes.
- [Configure and build](https://ambiqai.github.io/neuralspotx/getting-started/configure-and-build/): Resolve dependencies and compile a firmware image. This step needs no attached board.
- [Flash, reset and view](https://ambiqai.github.io/neuralspotx/getting-started/flash-and-view/): Connect your debug probe, program the board and inspect firmware output.
- [Extend your application](https://ambiqai.github.io/neuralspotx/getting-started/next-steps/): Add modules, explore examples and make the generated project your own.

Coming from legacy neuralSPOT? Read
[Migrating from neuralSPOT](https://ambiqai.github.io/neuralspotx/getting-started/migrate-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.