Setup Wizard

The Setup Wizard guides you through downloading the SDK or registering an existing SDK. It is suited to users setting up an Ameba development environment for the first time.

How to open: Command panel Advanced → Setup Wizard. When the SDK environment is not ready, you can also click the Setup Wizard button next to the SDK environment not ready. notice in the panel.

The wizard runs entirely in a standalone WebviewPanel. The steps are as follows:

Step

Name

Content

1

Environment check

Detects git; you can continue only after all checks pass. On Linux / macOS, Python (≥ 3.8) is also detected; Windows does not need this check.

2

Select SDK source

GitHub, Gitee (recommended for users in mainland China), or Use Existing Local SDK (use an SDK already on this machine).

3

Select SDK version

Branches and Release Tags are fetched dynamically from the selected source and shown in groups. The first branch is selected by default.

4

Select download type

SDK (base repository, small) or XDK (includes submodules such as audio, UI and AI algorithms, large).

5

Confirm & install

Shows a summary of Version / Type / Source / Destination. Click Start Download to begin the download.

6

Download

Progress bar plus a real-time scrolling log.

7

Done

Shows the SDK path and automatically completes the project configuration, see below.

Using an existing local SDK: After selecting Use Existing Local SDK in step 2, you can pick from the list of SDK paths used before, or click Browse… to specify an SDK root directory manually. Once the path passes validation, it is registered directly, steps 3 and 4 are skipped, and the confirm button becomes Use This SDK. Nothing is downloaded.

Download notes:

  • The SDK is downloaded to the ~/.realtek-ameba/<version>/ameba-rtos directory.

  • If a complete SDK already exists in that directory, a dialog appears. You can choose Use existing to use it directly, or Reinstall (overwrite) to delete it and download again. If the directory is incomplete (for example, a previous download was cancelled), it is cleaned up automatically and downloaded again.

  • If the download has not finished after about 60 seconds, a prompt appears; you can click Cancel & Switch Source to cancel and change the download source.

Automatic configuration after completion:

When the wizard finishes, the SDK path is recorded automatically in ~/.realtek-ameba/config.json, and the currently opened workspace is handled as follows:

  • External project: The .vscode configuration is generated automatically, with ameba.rootSDKPath pointing to this SDK. The currently selected chip is reused first, so you do not need to select one again.

  • SDK Root project: The current workspace is itself an SDK, and the extension keeps using the workspace’s own SDK. The wizard result is handled in one of three ways, depending on the SDK selected:

    • The selected SDK is the current workspace, and the workspace has no .vscode configuration yet (ameba.rootSDKPath is not set): the .vscode configuration is generated automatically.

    • The selected SDK is the current workspace, but a .vscode configuration already exists: the existing configuration is not overwritten, and only the panel status is refreshed.

    • The selected SDK is a different SDK (for example, you downloaded another version from within the current SDK project): the SDK path is only registered. The .vscode configuration of the current workspace is not modified, and the workspace does not switch to the new SDK. To use the new SDK, open its directory through File → Open Folder.

  • No workspace opened: Only the SDK path is registered. It takes effect after you open a project folder.

Note

The SDK paths recorded by the wizard appear in the SDK quick-pick lists of the later New External Project and Set Root SDK Path commands, so you do not need to enter them again.