Skip to main content

Getting Started

This page walks you from a fresh clone to a running Alp SDK example. If you already have a Zephyr toolchain, jump to step 3.

Two ways to develop

Pick whichever fits your workflow:

  • Hand-written firmware — write C against <alp/...> headers directly. The path covered below.
  • alp-studio codegen — drag-and-drop blocks; Studio emits the same <alp/...> API. See alp-studio.

The flow at a glance:

Prerequisites​

The SDK is supported equally on Linux, macOS, and Windows (native PowerShell or WSL2). Tooling versions are identical across hosts.

ToolVersionNotes
Zephyrv4.4.1Pinned by the SDK's west.yml and metadata/bootstrap.json.
Zephyr SDK1.0.1Pinned by metadata/toolchains.json. Real silicon only.
Python (bootstrap floor)3.10+prerequisites.pythonMinVersion — the host-universal floor the bootstrap scripts enforce.
Python (Zephyr build floor)3.12+zephyr.pythonMinVersion — Zephyr's real build floor. Not enforced by bootstrap.sh / bootstrap.ps1; Zephyr's own CMake enforces it at west build time.
Python depspyyaml, jsonschema, imgtoolInstalled by scripts/bootstrap.sh.
CMake3.20+find_package(Zephyr) minimum.
C compilerGCC 11+ / Clang 14+native_sim builds; cross-toolchain for real silicon.
west1.2+pip install west if your distro doesn't ship it.
tan CLI0.5.1The SDK's sole user-facing command. A Python program shipped as a self-contained PyInstaller freeze — no Rust toolchain, no rustup, no host Python interpreter. Installed by its own script; the SDK bootstrap does not install it.

The POSIX bootstrap prerequisites are git, cmake, python3, ninja, xz, and wget — ninja is a real prerequisite, not an optional extra. On Windows, 7-Zip is additionally required; it gates west sdk install, not bootstrap.ps1.

Per-platform install one-liners:

Homebrew
brew install git cmake python ninja xz wget
pip3 install west

For real-silicon builds you'll also need the Zephyr SDK, pinned at 1.0.1 by metadata/toolchains.json, and a JTAG/SWD probe.

Intel Mac: no Zephyr SDK target

The pinned Zephyr SDK ships a macos-aarch64 host archive only — there is no macos-x86_64. On an Intel Mac the west sdk install step has nothing to install, so real-silicon Zephyr builds need a Linux host instead. native_sim and the bootstrap step itself are unaffected.

Step 1 — Install tan, clone, and bootstrap​

Install tan first — bootstrapping the SDK is itself a tan verb. The canonical first-install sequence:

First install
git clone https://github.com/alplabai/alp-sdk
cd alp-sdk

curl -fsSL https://raw.githubusercontent.com/alplabai/tan-cli/main/install.sh | sh
# Windows PowerShell: irm https://raw.githubusercontent.com/alplabai/tan-cli/main/install.ps1 | iex

tan bootstrap --sdk-root "$PWD"
tan doctor

( cd .. && west sdk install --gnu-toolchains arm-zephyr-eabi --no-hosttools \
    --install-dir "$PWD/zephyr-sdk" )
export ZEPHYR_SDK_INSTALL_DIR="$PWD/../zephyr-sdk"

tan init --name my-app --destination .. --sdk-root "$PWD"
cd ../my-app
tan build

Every customer-facing step leads with tan; west appears exactly once, for the one-time SDK toolchain install — tan sdk install / tan sdk switch are not ported yet.

The SDK also ships its bootstrap script, if you'd rather run it directly:

Clone + bootstrap
git clone https://github.com/alplabai/alp-sdk
cd alp-sdk
bash scripts/bootstrap.sh
source ../.venv/bin/activate
export ZEPHYR_BASE="$PWD/../zephyr"

scripts/bootstrap.sh makes the alp-sdk checkout's parent the west workspace (west init -l), runs west update --narrow, installs west + the SDK's Python deps and an editable alp_cli — an SDK-side Python package, not a command of its own — into a workspace venv (your system Python is never touched), and prints host-specific hints for the optional native libraries the Yocto backends need. It's idempotent, and it reuses an existing $ZEPHYR_BASE workspace only when it's a compatible v4.4.x tree whose manifest is this checkout. It enforces the 3.10 host Python floor and nothing more — Zephyr's 3.12 build floor is checked only later, by Zephyr's own CMake.

Bootstrap does not give you a command to run

There is no alp binary installed anywhere — pyproject.toml registers only alp-mcp. tan does not shell out to alp_cli: since v0.5.0-rc1 tan is itself a Python program and carries its own implementations. Install tan before you build anything.

The layout it produces — alp-sdk is the manifest repo, so the topdir is its parent:

<parent>/                # west topdir
├── alp-sdk/             # this repo — the workspace manifest
├── .west/
├── .venv/               # hermetic west + Zephyr Python deps
├── zephyr/              # v4.4.1
└── modules/
Changed in v0.10.1

Bootstrap used to create a separate zephyrproject/ workspace from the upstream Zephyr manifest, which left alp-sdk as a non-manifest project — so west never discovered the SDK's extension commands and every west alp-* command failed with "unknown command" (#769). It now inits from alp-sdk's own west.yml, which both registers the surviving west alp-* commands and moves the topdir to the checkout's parent. If you bootstrapped earlier, re-run on a fresh clone; ../zephyrproject/zephyr is no longer the right ZEPHYR_BASE.

On native Windows, run the PowerShell-7+ companion instead:

Native Windows (PowerShell)
git clone https://github.com/alplabai/alp-sdk
cd alp-sdk
pwsh scripts\bootstrap.ps1
& ..\.venv\Scripts\Activate.ps1
$env:ZEPHYR_BASE = "$PWD\..\zephyr"

bootstrap.ps1 won't install git / CMake / Python / Ninja for you (it prints the matching winget install line and exits if one is missing) and leaves the Arm toolchain + Zephyr SDK as manual installs. native_sim isn't available on native Windows — use WSL2 for the simulator + Yocto halves.

Bootstrapped on Windows before v0.11.0? Your layout is stale

Through v0.10.1 the #769 fix had landed in bootstrap.sh only, so bootstrap.ps1 initialised from the upstream Zephyr manifest into a zephyrproject\ sibling, leaving every west alp-* command an "unknown command". As of v0.11.0 bootstrap.ps1 produces the same layout as bootstrap.sh. Re-run pwsh scripts\bootstrap.ps1 on a fresh clone and update ZEPHYR_BASE — the old ..\zephyrproject\zephyr path no longer applies, and the old workspace is not reused. See Installation.

Install the tan CLI​

tan is the SDK's sole user-facing command — scaffolding, validating, generating, host preflight, serial console, diagnostics, and building / flashing / sizing / bundling / cleaning / Renode-booting. It ships from its own repo (alplabai/tan-cli) on its own version line — currently 0.5.1 — so you install it separately from the SDK bootstrap, and before it.

tan is a Python program, released as self-contained PyInstaller --onedir freezes. The install script puts a ready-to-run freeze on your PATH; there is no Rust toolchain, no rustup, and no Python interpreter to provide.

One-time
curl -fsSL https://raw.githubusercontent.com/alplabai/tan-cli/main/install.sh | sh
Windows PowerShell
irm https://raw.githubusercontent.com/alplabai/tan-cli/main/install.ps1 | iex

From a source checkout instead: pip install ./python.

Everything then runs inside that one program — no verb forwards to python -m alp_cli:

  • build / flash / size / image / clean / renode — tan's own build executor. Per ADR 0020, alp-sdk is plans-only for this surface: tan runs west / bitbake / cmake per slice itself.
  • model, monitor, faultdecode, new-som — native Python inside tan.
  • generate — renders in-process from tan.planner; spawning the SDK's scripts/alp_project.py is an opt-in escape hatch behind TAN_GENERATE_EXECUTOR=subprocess. There is no tan emit verb — use tan generate --target <target>.

Step 2 — Set up the Zephyr workspace (alternative)​

If you'd rather drive west directly — works on every host:

mkdir alp-workspace && cd alp-workspace
west init -m https://github.com/alplabai/alp-sdk
west update --narrow -o=--depth=1
west zephyr-export
export ZEPHYR_BASE="$PWD/zephyr"

After this the topdir contains zephyr/ (v4.4.1, pinned by the SDK's west.yml), the standard Zephyr modules, and alp-sdk/ as the workspace manifest. Initialising from alp-sdk's manifest is what registers the surviving west alp-* commands — west alp-migrate (board.yaml schema migration), west alp-lock (dependency lockfile), west alp-quality (quality-task registry) and west alp-emit (the generated-artefact subset). Building is not among them: that surface belongs to tan.

Step 3 — Build the GPIO example​

tan is the single front door — from inside a project it finds board.yaml, builds every core, and (on native_sim) runs the result in one step:

cd alp-sdk/examples/peripheral-io/gpio-button-led
tan run                    # build for native_sim + execute

There is no --board selector: the target comes from the project's own board.yaml — native_sim/native/64 on your host or real silicon. From outside the project directory, point tan at it instead:

tan --project alp-sdk/examples/peripheral-io/gpio-button-led build

Expected output:

*** Booting Zephyr OS build v4.4.1 ***
[gpio] init button=BOARD_PIN_ENCODER_SW, led=BOARD_PIN_LED_RED
[gpio] led=0 status=0
[gpio] led=1 status=0
...
[gpio] done

tan build validates the example's board.yaml (via alp-sdk's alp_orchestrate), generates alp.conf + the build-time <alp_hw_info_build.h> companion header, and delegates to west build per slice. See the board.yaml reference for the schema.

alp-sdk's own contribution to that pipeline is inspectable without tan — it emits plans, it never builds:

PYTHONPATH=scripts python3 -m alp_orchestrate --input board.yaml --emit build-plan
PYTHONPATH=scripts python3 -m alp_orchestrate --input board.yaml --emit system-manifest

Step 4 — Target real hardware​

For an Alp Lab EVK (or your own board), tan builds every core from the project's board.yaml and programs the whole system over its registered flash backends. Nothing changes on the command line between native_sim and real silicon — the target lives in board.yaml:

cd alp-sdk/examples/peripheral-io/gpio-button-led
tan build && tan flash

From the workspace topdir, name the project instead:

# AEN family on the E1M EVK
tan --project alp-sdk/examples/peripheral-io/gpio-button-led build
tan flash alp-sdk/examples/peripheral-io/gpio-button-led

# V2N family on the E1M-X EVK — helper MCU (GD32 bridge) only, preview first
tan flash alp-sdk/examples/v2n/v2n-gd32-bridge-ping --helper gd32_bridge --dry-run
tan flash alp-sdk/examples/v2n/v2n-gd32-bridge-ping --helper gd32_bridge

Board files ship in-tree under zephyr/boards/alp/ (exposed via zephyr/module.yml's board_root) — nothing extra to fetch.

To order an Alp Lab EVK, request a dev kit.

What next?​

Questions about this page? Discuss in Community Forum