VS Code User Guide

Overview

The Ameba extension is a VS Code extension developed based on Cline. It retains all the native features of Cline while adding specialized functions for the Realtek Ameba series of chips, including development environment checks and automatic installation, SDK configuration, code compilation, firmware flashing, and serial monitoring. These features are provided through an intuitive button interface, simplifying the development workflow for the Ameba series.

Cline Resources

• Cline Official Documentation

• Cline GitHub Repository

• AmebaSerialServer

Getting Started

1. Installing the Extension

   In the VS Code Marketplace, search for Ameba and click install.

2. Using Ameba-only Features

   • On the welcome page shown on first use, you can log in with a Cline account or use a custom API Key.

   • If you do not have a Cline account or API key, you can click the USE Ameba Only button to use only the Ameba-related features.

   

3. Ameba Feature Area

   The red box in the figure below highlights the Ameba-related feature area.

   

4. Environment Check and Auto-Installation

   The extension automatically checks the following configurations:

   • Whether the opened folder or its subfolders contain the Ameba SDK. For SDK download, refer to FreeRTOS SDK Download .

   • Whether the prebuilts for the development environment are installed correctly. If not, two installation options will be provided in the bottom-right corner: Install from GitHub and Install from Aliyun (users in mainland China are recommended to use Aliyun). Click to automatically download and install the prebuilts, and the Python virtual environment will also be automatically created.

   

   • If the prebuilts for the development environment are installed correctly, but the Python virtual environment for the SDK has not been created correctly, a notification will appear in the bottom-right corner. Click the Setup Now button to automatically create it.

   

   The Ameba-related feature buttons will only be activated after all the above checks have passed.

5. Chip Selection

   Select the Ameba series chip you want to develop for from the dropdown menu.

   

6. Serial Port Selection

   The extension automatically scans and updates all available serial ports in the system. Select the corresponding serial port for your development board from the dropdown menu.

   

7. Example Selection

   • Select the corresponding application example from the dropdown menu.

   • After selecting an example, a preview of its corresponding README.md file will be opened.

   • By default, or by selecting None in the examples, the base project configuration will be compiled.

   

Main Features

SDK Menuconfig

1. Click the Ameba Menuconfig button to open the graphical SDK menuconfig.

2. For more information on SDK menuconfig, refer to Configure SDK (menuconfig) .

3. After finishing the SDK menuconfig, you must save and exit menuconfig interface correctly. If you do not save and exit correctly, it will affect the normal use of other functions. A notification will appear in the bottom-right corner to remind users.

Project Compilation

1. Click the Ameba Build button to compile the project.

   • If an application example has been selected in the dropdown menu, the specified example will be compiled.

   • If no application example is selected or None is selected in the examples, the basic project configuration will be compiled.

2. The compilation process will display detailed progress and log information in real-time.

Firmware Flashing

1. Click the Ameba Flash button to start the firmware flashing process.

2. Flashing based on SDK configuration and Flash Layout Information .

   • Open Flash Layout Information for user convenience.

   • Check Flash Layout Information to prevent abnormal configurations (such as overlap), and notify users when abnormalities occur.

3. It provides real-time feedback on flashing progress and detailed logs.

Serial Monitor

1. Click the Ameba Monitor button to open the integrated serial monitor, which automatically selects the baud rate and connects to the serial port.

2. Display and receive serial data in real-time.

3. Support sending AT commands through the serial port, with auto-completion based on the supported ATCMD List using the Tab key.

4. Support history function, click the ↑ key to quickly view and select previously sent commands.

Online Documentation

Click the Ameba Doc button to open the default browser and navigate to the official Realtek Ameba website.

Advanced Features

Remote Serial Port Flashing and Monitoring

If your local machine is a Windows system, the development board is connected to it, but you choose to have the SDK on a Linux server and develop using the VS Code Remote-SSH extension, you can follow these steps:

1. Download AmebaSerialServer and run it on your local Windows machine. By default, it starts without a password. If security is a concern, you can right-click the software icon to configure a password.

2. In VS Code, press F1, type ameba: Remote Servers, and click the corresponding option.

3. Click the Add New Remote Server option.

   Server Name:

   Enter a custom name for the server.

   Server Address:

   Enter the IP address of your local Windows machine.

   Server Password:

   If you have configured a password for the server software, enter it here. Otherwise, press Enter to skip.

4. After successful configuration, if VS Code is connected to the Ameba SDK via Remote-SSH, the serial port list will be updated with remote serial port information. You can select it for remote flashing and monitoring.

5. Pressing F1 again in VS Code and entering ameba: Remote Servers allows you to view existing server information. You can click on an existing server to delete it.

Troubleshooting

When encountering issues while using the Ameba extension, you can follow these troubleshooting steps:

Extension Installation Failure

Issue: Extension cannot be installed properly or fails to start after installation

Solution: Check system environment version requirements and ensure the following minimum versions are met:

• VS Code version ≥ 1.84.0

• Node.js version ≥ 18.16.0

You can check version information through the following methods:

• Menu bar Help → About to view version number

If the versions do not meet the requirements, please upgrade to the corresponding versions first and then reinstall the extension.

Terminal-Related Issues

Issue: Extension functions abnormal, command execution failure, or interface unresponsive

Solution: The extension’s core functions are executed through creating a dedicated terminal named Ameba. When abnormalities occur:

• If you find that the Ameba terminal has errors or is unresponsive, manually close it

• The extension will automatically detect and recreate the Ameba terminal when executing functions next time

• After closing the abnormal terminal, click the corresponding function button again to use it normally

Toolchain Path Modification Issues

Issue: After modifying the toolchain installation path, the extension cannot properly recognize the development environment or functions abnormally

Solution: If you have modified the toolchain installation path (refer to Installing Toolchain ), you need to perform the following steps:

• Completely close VS Code (ensure all VS Code windows are closed, simply reloading the window is not sufficient)

• Restart VS Code and open the Ameba SDK project

• The extension will automatically re-detect the development environment configuration and update the relevant path information