Ameba-aiot
A VS Code extension for Realtek Ameba series IoT development, providing an integrated toolchain for building, flashing, debugging, and project management.
📖 Full Documentation
Features
🛠 Project Management
- Setup Wizard — guided SDK download and installation; supports downloading a new SDK or registering an existing local SDK
- New External Project — step-by-step wizard to create an external project from an SDK template, with auto-generated
.vscode configuration
- Import External Project — import an existing project and generate
.vscode configuration automatically
- Set Root SDK Path — create or update
settings.json, c_cpp_properties.json, and .clangd for any project; existing files are merged, not overwritten
⚙️ Build & Flash
- Menuconfig — graphical Kconfig editor (Visual Editor WebView) or classic terminal mode
- Build — compile the project with one click or keyboard shortcut
- Clean / Full Clean — remove build artifacts
- Flash — local and remote firmware flashing with configurable baud rate, memory type, and chip-erase options
🔌 Monitor & Debug
- Serial Monitor — local and remote serial port monitoring with optional log save
- Debug — local and remote GDB debugging via OpenOCD, with multi-core support (J-Link / DAPLink)
🔍 IntelliSense & Code Navigation
- Auto-configures clangd (
--compile-commands-dir) when the clangd extension is installed
- Falls back to cpptools
c_cpp_properties.json when clangd is not available
🌐 Remote Operations
- Remote Servers — manage remote build/flash/monitor/debug servers
- Flash, monitor, and debug over SSH without a physical board connection
🔎 Environment Detection
- Automatically detects the SDK root on activation — searches down into the workspace and up through parent directories (BFS + ancestor walk)
- Supports SDK root projects (Case A) and external projects with a separate SDK (Case B)
- Prompts to create
.vscode configuration when an external project has no Ameba settings
Supported Chips
RTL8730E · RTL8711Dx · RTL8721Dx · RTL8720E · RTL8726E · RTL8710E · RTL8713E · RTL8721F · RTL8711F · RTL872xD · RTL8710F · RTL8720F
Requirements
| Requirement |
Notes |
| VS Code 1.84+ |
Required |
| Python 3 3.8+ |
Required for Menuconfig Visual Editor |
| Ameba SDK |
Clone from Ameba-AIoT GitHub or use the Setup Wizard |
| OpenOCD |
Required only for debugging |
Getting Started
1. Install the Extension
Search for Ameba-aiot in the VS Code Extensions panel, or install via the CLI:
code --install-extension Realtek.ameba-aiot
2. Open Your Project
Case A — SDK root project
Open the Ameba SDK root directory in VS Code. The extension detects the SDK automatically.
Case B — External project
Open your project directory. If no Ameba settings are found, the extension will prompt you to configure the SDK.
- Open the Command Palette (
Ctrl+Shift+P / Cmd+Shift+P) and run Ameba: Setup Wizard
- Follow the wizard to select your chip and set up the SDK
- The extension writes
.vscode/settings.json and c_cpp_properties.json automatically
3. Key Commands
| Command |
Shortcut |
Description |
Ameba: Build Project |
Ctrl+Alt+B |
Compile the project |
Ameba: Flash Device |
Ctrl+Alt+F |
Flash firmware to the board |
Ameba: Monitor Device |
Ctrl+Alt+M |
Open serial monitor |
Ameba: Menuconfig Visual Editor |
— |
Open the WebView Kconfig editor |
Ameba: Start Debugger |
— |
Start a debug session |
Ameba: Setup Wizard |
— |
Download or register an SDK |
Ameba: Import External Project |
— |
Import and configure an existing project |
Extension Settings
All settings are workspace-scoped unless noted otherwise.
| Setting |
Default |
Description |
ameba.menuconfig.mode |
"editor" |
"editor" — Visual WebView editor; "classic" — terminal-based menuconfig |
Monitor
| Setting |
Default |
Description |
ameba.monitor.resetBoard |
true |
Send a reset signal to the board when starting the monitor |
ameba.monitor.enableLog |
false |
Save serial output to a log file |
ameba.monitor.logDirectory |
"" |
Directory for log files (defaults to workspace root) |
Flash
| Setting |
Default |
Description |
ameba.flash.baudRate |
2000000 |
Serial baud rate (115200 / 500000 / 1M / 1.5M / 2M / 3M / 4M) |
ameba.flash.memoryType |
"Nor" |
Flash memory type: "Nor" or "Nand" |
ameba.flash.eraseChip |
false |
Erase the entire chip before flashing |
ameba.flash.resetBoard |
true |
Send a reset signal after flashing completes |
ameba.flash.includeVfs |
false |
Include the VFS partition when flashing |
Debug
| Setting |
Default |
Description |
ameba.debug.adapterType |
"daplink" |
Debug adapter: "daplink" or "jlink" |
ameba.debug.adapterSpeed |
4000 |
JTAG/SWD clock speed in kHz |
ameba.debug.requestType |
"attach" |
Debug request type: "attach" or "launch" |
ameba.debug.runToEntryPoint |
"main" |
Break at this function on launch; leave empty to disable |
ameba.debug.allStop |
true |
Enable all-stop mode (all cores halt together) |
ameba.debug.runSync |
false |
Synchronize run state across all cores |
ameba.debug.liveWatch |
false |
Enable live watch expressions |
Development Setup
Prerequisites
Quick Start
git clone https://github.com/Ameba-AIoT/ameba-vscode-extension.git
cd ameba-vscode-extension
# Install all dependencies (extension + webview-ui)
npm run install:all
Press F5 in VS Code to open a new Extension Development Host window.
If build errors appear, install the esbuild problem matchers extension.
Useful Scripts
npm run compile # TypeScript compile + lint
npm run watch # Watch mode (esbuild + tsc)
npm run check-types # Type-check only
npm run lint # Biome lint + buf lint
npm run format:fix # Auto-fix formatting
npm run test # Run all tests
npm run package # Package .vsix
For full contributor guidelines, see CONTRIBUTING.md.
Code Structure
src/
├── extension.ts # Extension entry point; registers VS Code commands
├── core/controller/
│ ├── index.ts # Controller class (global state hub)
│ └── ameba/ # Command implementations (one file per command)
│ ├── amebaEnvManager.ts # SDK detection, toolchain installation, env management
│ ├── amebaBuild.ts # ameba.build
│ ├── amebaFlash.ts # ameba.flash
│ ├── amebaMonitor.ts # ameba.monitor
│ ├── amebaDebugger.ts # ameba.debug
│ └── ...
├── hosts/vscode/
│ ├── AmebaSetupWizardPanel.ts # Setup Wizard WebviewPanel
│ ├── AmebaNewProjectPanel.ts # New External Project WebviewPanel
│ └── AmebaStatusBar.ts # Status bar manager
└── shared/proto/ameba/ # Proto type definitions
webview-ui/src/
├── App.tsx # React root
└── components/ameba/ # Ameba UI components
Contributing
See CONTRIBUTING.md for guidelines on reporting bugs, proposing features, and submitting pull requests.
License
Apache 2.0
