VS Code 使用指南

概述

Ameba 扩展插件是基于 Cline 开发的 VS Code 扩展插件，保留了原生 Cline 的所有功能，并针对 Realtek Ameba 系列芯片增加了开发环境检查和自动安装，SDK 配置、代码编译、固件烧录、串口监控等专用功能。这些功能通过直观的按钮界面提供，简化了 Ameba 系列芯片的开发流程。

Cline 相关资料

使用流程

  1. 插件的安装

    在 VS Code 的扩展应用商店中搜索 Ameba，点击 安装 即可

  2. 仅使用 Ameba 功能

    • 首次使用的欢迎页面中可以登录 cline 账号或者使用自定义的 API Key

    • 当您没有 Cline 账户或 API key 时，可以点击 USE Ameba Only 按钮仅使用 Ameba 相关功能

    ../_images/vsix_welcome.gif

  3. Ameba 相关功能区

    下图中的红框展示了 Ameba 相关的功能区域

    ../_images/vsix_ameba_area.png

  4. 开发环境检查和自动安装

    插件会自动检查如下配置:

    • 打开的文件夹和子文件夹内是否包含 Ameba SDK，SDK 的下载请参考 FreeRTOS SDK 下载

    • 开发环境的软件合集包是否已正确安装，如果没有安装，将会在右下角提供 Install from GitHub 和 Install from Aliyun 两种安装选项（中国大陆地区用户建议使用 Aliyun），点击即可自动下载安装并创建 Python 虚拟环境

    ../_images/vsix_check_prebuilts.gif

    • 如果开发环境的软件合集包已正确安装，但 SDK 的 Python 虚拟环境未正确创建，将会在右下角进行提示，点击 Setup Now 按钮即可自动创建

    ../_images/vsix_check_venv.gif

    通过上述所有检查后，插件才会激活 Ameba 相关功能按钮

  5. 芯片选择

    通过下拉选择框选择要开发的 Ameba 系列芯片型号

    ../_images/vsix_ic_select.gif

  6. 串口选择

    自动扫描并更新系统中所有可用串口，通过下拉选择框选择开发板对应的串口名

    ../_images/vsix_port_select.gif

  7. 示例选择

    • 通过下拉选择框选择对应的应用示例

    • 选择示例后将打开对应示例的 README.md 的预览

    • 默认情况下或者选择示例中的 None 将会编译基础项目配置

    ../_images/vsix_example_select.gif

主要功能

SDK 配置

  1. 点击 Ameba Menuconfig 按钮打开图形化 SDK 配置界面

  2. SDK 配置相关信息请参考 配置 SDK（menuconfig）

  3. 完成 SDK 配置后，必须保存并正确退出配置界面。如果未正确保存退出，将会影响后续的其余功能正常使用，插件会在右下角弹出提示信息提醒用户

../_images/vsix_config.gif

项目编译

  1. 点击 Ameba Build 按钮进行编译工程

    • 如果已在下拉选择框选择应用示例，则编译指定示例

    • 如果没有选择应用示例或者选择示例中的 None，则编译基础项目配置

  2. 编译过程中将实时显示详细进度和日志信息

../_images/vsix_build.gif

固件烧录

  1. 点击 Ameba Flash 按钮启动固件烧录流程

  2. 根据 SDK 配置和 Flash 布局信息 进行烧录

  3. 提供烧录进度实时反馈和详细日志

../_images/vsix_flash.gif

串口监控

  1. 点击 Ameba Monitor 按钮打开集成的串口监视器，自动选择波特率并连接串口

  2. 实时显示和接收串口数据

  3. 支持通过串口发送 AT 命令，并且可以根据支持的 ATCMD List 通过 Tab 键 自动补全

  4. 支持历史记录功能，按 ↑ 键 可以快速查看和选择之前发送过的命令

../_images/vsix_monitor.gif

在线文档

点击 Ameba Doc 按钮将，打开默认浏览器，跳转到 Realtek Ameba 的官方网页

../_images/vsix_doc.gif

高级功能

远程串口烧录和监控

如果您本机电脑是 Windows 系统，开发板也连接到本机电脑，但是选择将 SDK 下载到 Linux 服务器，通过 VS Code 的 Remote-SSH 的扩展进行 SDK 的开发，请按照如下步骤进行：

  1. 在本机电脑下载 AmebaSerialServer 并启动，启动后默认不配置密码，有安全需要可以右击软件图置密码

  2. 在 VS Code 中按下键盘 F1 按键，输入 ameba: Remote Servers，点击对应的选项

  3. 点击 Add New Remote Server 选项

    Server 名称:

    输入想要自定义的服务器名称

    Server 地址:

    输入 Windows 本机电脑的 IP 地址

    Server 密码:

    如果 Windows 的服务器软件有配置密码，需要输入对应的密码，如服务器未设置，则直接回车跳过

  4. 配置成功后，如果 VS Code 通过 Remote-SSH 连接打开了 Ameba SDK，串口列表会更新出远程串口信息，选择后可以进行远程串口的烧录和监控

  5. 再次在 VS Code 中按下键盘 F1 按键，输入 ameba: Remote Servers，点击对应的选项可以查看已有 Server 信息，点击对应已有 Server 可以将其删除

../_images/vsix_remote_server.gif

故障排除

当使用 Ameba 扩展插件时遇到问题，可以按照以下步骤进行故障排除：

插件安装失败

问题现象： 插件无法正常安装或安装后无法启动

解决方案： 检查系统环境版本要求，确保满足以下最低版本要求：

  • VS Code 版本需要 ≥ 1.84.0

  • Node.js 版本需要 ≥ 18.16.0

可以通过以下方式检查版本信息：

  • 菜单栏 帮助 → 关于 查看版本号

../_images/vsix_vscode_version.png

如果版本不满足要求，请先升级到对应版本后重新安装插件。

终端相关问题

问题现象： 插件功能异常、命令执行失败、或界面无响应

解决方案： 插件的核心功能是通过创建一个名为 Ameba 的专用终端来执行，当出现异常时：

  • 如果发现 Ameba 终端出现错误或无响应，请手动关闭

  • 插件会自动检测，并在下次执行功能时重新创建 Ameba 终端

  • 关闭异常终端后，重新点击相应的功能按钮即可正常使用

../_images/vsix_ameba_terminal.png

工具链路径修改后插件异常

问题现象： 修改工具链安装路径后，插件无法正常识别开发环境或功能异常

解决方案： 如果您修改了工具链的安装路径（参考 安装工具链 ），需要执行以下步骤：

  • 彻底关闭 VS Code（确保所有 VS Code 窗口都已关闭，仅重新加载窗口是不够的）

  • 重新启动 VS Code 并打开 Ameba SDK 项目

  • 插件会自动重新检测开发环境配置并更新相关路径信息