介绍

本页介绍如何使用 PlatformIO 和 VSCode 编译 Grbl_Esp32。

你的起点

• 强制的
  • 一些C++编程经验
  • 基本的 CNC 知识
  • 带有 USB 数据线的 ESP32 DevKit 开发板
• 选修的
  • 完整的硬件，如Bart’s Tindie board
  • 一台工作的 CNC 机器（包括电机驱动器、步进器、按钮等）

PlatformIO 与 Arduino ID

Arduino IDE是用于微控制器软件开发的易于使用的“集成开发环境”(IDE)。IDE意味着代码编辑、程序编译、编译后的代码下载到微​​处理器和测试都可以在一个环境中完成。它最初是为 Arduino 硬件设计的，但现在已经适用于许多不同的微控制器，包括 ESP32。它稳定，文档齐全，并且非常易于用于小型项目。对于较大的项目，它的简单性可能会受到限制。

Grbl_Esp32 是一个相对较大的项目，它突破了 Arduino IDE 的极限。一个主要的烦恼是，如果您更改任何内容，Arduino IDE 会重新编译所有代码，甚至是未更改的部分。所花费的时间会阻碍开发，您通常需要进行一系列小的更改并快速测试它们。此外，Arduino IDE 对版本控制、代码审查、多个程序员之间的协作和问题跟踪等专业代码管理实践没有很好的支持。

为了克服这些限制，Grbl_Esp32 核心开发人员改为使用PlatformIO微控制器编译系统，以及Visual Studio Code (VSCode) 编辑系统。PlatformIO 处理设置微控制器编译器、开发框架、库和电路板配置、将代码加载到微控制器以及测试的细节。VSCode 拥有大量用于编辑和管理源代码的工具，通过点击式集成到 PlatformIO 和源代码管理系统，如 git 和 GitHub。PlatformIO 和 VSCode 的组合提供了 Arduino IDE 的替代品，它更快（在初始设置之后）并且功能更强大。

（PlatformIO 也适用于其他编辑系统，如 Atom、Sublime Text、EMACS、Visual Studio 和 vi。如果您更喜欢其他编辑器之一，请在网上搜索有关在您的编辑器中使用 PlatformIO 的说明。为简单起见，本文档描述了只有 VSCode 案例。）

VSCode 有许多用于处理常见编程情况的扩展。除了 PlatformIO 扩展之外，本文档还建议了其他一些特别适合与 Grbl_Esp32 一起使用的扩展。

让我们来看看全新安装，最后将 Grbl_Esp32 上传到 ESP32 上进行首次测试。

安装 VSCode & PlatformIO

1. 混帐

Grbl_ESP32 项目使用Git版本控制系统来跟踪代码的更改，并结合 GitHub 网络服务在云中存储代码。使用 git 并不是绝对必要的——您可以只下载一个带有给定版本的源代码的 .zip 文件——但是 git 有很多优点。您可以轻松跟踪不​​同版本的代码，在已发布代码和实验代码之间来回切换，将建议的更改发送回核心开发人员等。

如果你的机器上已经有 git，VSCode 将使用现有的安装。如果没有，请先安装 git。有关 Git 的更多信息，请参见Git 文档。

2.VS代码

按照文档安装Visual Studio Code。在 Windows 中全新安装 VSCode，如下所示。

3.平台IO扩展

单击左下角的“齿轮”图标并选择扩展，打开 VSCode 扩展选项卡。在顶部的“在 Marketplace 中搜索扩展”框中，键入“platformio”，选择“PlatformIO IDE”扩展，然后使用蓝色的“安装”按钮安装它。

4. GitLens 扩展（可选）

GitLens扩展为VSCode提供了代码比较和 git 的全部功能。这对于需要详细查看代码随时间变化情况的开发人员特别有用。如上所述，在扩展管理器中搜索“GitLens”并安装它。见下图。

5. C/C++扩展

大多数 Grbl_Esp32 源代码是用 C/C++ 编写的。有各种不同的扩展可以帮助 C/C++ 开发——突出显示关键字、即时错误检查、显示函数参数等。Microsoft 的C /C++扩展效果很好。见下图。

6. 已安装扩展的最终概述

至此，安装完成。下一步是项目设置。

将 Grbl_Esp32 导入 VSCode/PlatformIO

Grbl_Esp32 源代码包含一个“platformio.ini”文件，告诉 PlatformIO 如何编译它。

如果您的计算机上已有 Grbl_Esp32 源代码，只需从顶部菜单栏转到文件>打开文件夹，然后选择包含 Grbl_Esp32 的文件夹。该文件夹中“platformio.ini”的存在将激活 PlatformIO 扩展。

如果您还没有源代码，可以直接从 VSCode 中获取。在 VSCode 侧边栏中，单击 PlatformIO 的“外星人”图标以调出“PLATFORMIO：QUICK ACCESS”面板，然后选择 Clone Git Project。

在顶部，您将看到一个框，上面写着“提供存储库 URL 或选择存储库源”。将https://github.com/bdring/Grbl_Esp32粘贴到该框中，然后单击出现在其下方的 Clone from URL … 行。

这将打开一个文件选择器对话框，您可以在其中选择将包含新的“Grbl_Esp32”子目录的目录。然后你会看到

然后

单击打开，VSCode 将连接到 Grbl_Esp32 源代码。

自定义“Grbl_Esp32/src/Machine.h”

每台 CNC 机器都需要一些特定的机器设置。Grbl_ESP32 默认为什么都不做的“test_drive.h”机器定义。您最终将需要设置一个真实的机器定义文件。

文件Grbl_Esp32/src/Machine.h包含行#include "src/Machines/test_drive.h"。它选择“test_drive”机器——一个虚拟的 3 轴机器，你可以安全地在 ESP32 开发模块上单独使用或连接到任何硬件。它实际上不会改变任何引脚的状态，因此可以安全使用，无需担心浮动输入引脚或短路输出引脚。

要与实际硬件一起使用，您必须使用 Grbl_Esp32/src/Machines/ 子目录中现有的机器定义文件之一，或者创建您自己的机器定义文件。例如，Grbl_ESP32 开发板使用文件 Machines/3axis_v4.h。如果您的硬件与其中一台预定义的机器不匹配，您可以创建自己的文件，也许使用其中一台预定义的机器作为起点。请参阅此维基页面。在 Machine.h 中，#include 您的文件而不是 Machines/test_drive.h。

您可以使用 VSCode 来编辑文件，如图所示

如何编译 Grbl_Esp32（USB、无线、Web UI）

VSCode PlatformIO 扩展在窗口底部的状态栏中添加了一些图标

您可以将鼠标悬停在图标上以验证其功能。

“复选标记”图标从源代码编译（“构建”）固件，但不会将其上传到 ESP32 模块。编译过程以及由此产生的任何错误都显示在 VSCode“终端”窗格中。

“右箭头”图标编译，如果成功，则上传到 ESP32 模块。这是您最常使用的一种。

“垃圾桶”图标执行“清洁”步骤。在大多数情况下，PlatformIO 可以检测到源文件何时发生更改，并且只会重新编译更改的文件，从而加快您进行小更改后后续重新编译的过程。在少数情况下——尤其是当你在 Custom/ 文件夹中进行更改时——更改检测不起作用，因此你必须强制 PlatformIO 重新编译所有内容。这就是“干净”的目的——它丢弃所有以前的编译结果，因此编译过程从一个干净的状态开始并编译所有内容。

“电源插头”图标启动一个连接到 ESP32 串行端口的串行监视器，因此您可以串行地与 Grbl_Esp32 交互。

正常过程是“上传”（自动执行编译步骤），然后是“串行监视器”。

可能出现的问题

• 如果你有一个来自你之前完成的工作的现有 PlatformIO 安装，那么旧安装可能会干扰新工作。PlatformIO 在目录UserHomeDirectory /.platformio中存储了很多工具。（在 Windows 上，UserHomeDirectory通常是“C:/Users/YourUserName”）。这些工具的旧版本可能无法正常工作。在这种情况下，您可以尝试删除或重命名旧的 .platformio 目录。然后你将不得不使用 VSCode 的扩展管理器来卸载然后（重新）安装 PlatformIO 扩展。系统可能会提示您重新加载 VSCode 几次；询问互联网如何做到这一点。

通过USB上传

现在通过 USB 将 ESP32 开发板连接到您的 PC。请记住，此基本程序与芯片有关，与电路板无关。换句话说，你可以采取

• 乐鑫 DevKit 开发板
• Bart´s Grbl_ESP32 CNC开发板V4.1

• 你自己的董事会

提示

• 一些 ESP32 开发板需要按下 EN 按钮才能启动编程。这可以通过添加一个电容器来补偿
• PlatformIO 会自动识别与 ESP32 开发板的 USB 连接。如有问题，请参阅上传选项

通过 OTA（无线）上传

此步骤不适用于出厂时全新的 ESP32 芯片。在第一次使用 Grbl_Esp32 刷机后，这是一个非常有用的功能，因为无需物理访问硬件就可以刷机。

先决条件

• Grbl_Esp32 第一次闪现
• OTA 在 Grbl_Esp32 中启用
• 路由器，安全，…设置
• 已连接天线（如适用）
• Grbl_Esp32 Web UI 可通过 WIFI 访问
• 通过 Web UI 手动上传固件进行试驾，以确保它一次有效

话虽如此，将这些行添加到主文件夹中的platformio.ini文件中

[env]
upload_protocol = espota
upload_port = 192.168.xx.xx

upload_port是您机器的 IP 地址。

单击蓝色功能区中的PlatformIO::Upload按钮

Uploading: [============================================================] 99%
Uploading: [============================================================] 99%
Uploading: [============================================================] 100% Done...


13:31:35 [INFO]: Waiting for result...
13:31:36 [INFO]: Result: OK
13:31:36 [INFO]: Success

通过 ESP32 Web UI 上传

ESP32 Web UI 运行后，您还可以通过 Web UI上传生成的firmware.bin文件。

提示

• 可能调整您的 PC 防火墙以允许传入流量（问题）
• 测试 ESP32 连通性。预期的结果，例如通过 USB cooenction 连接看起来像这样
• 将工作良好的 firmware.bin 文件与工作存储库一起存档作为备份可能会有所帮助。以防万一 变得很奇怪，你需要回到最近定义的起点

从这往哪儿走

• Grbl_Esp32 维基

常见问题

• 主分支是稳定环境，你会在打开 GitHub 网站时看到它。还有其他分支，如devt或 ones 来尝试特定的功能。

未分类的 wiki 增强功能，取决于用户兴趣

• 更新 Grbl_Esp32
• 更新 ESP32 固件（当前版本 AT 2.1）
• Fork Grbl_Esp32 并使用 GitHub 维护自己的编程
• 简单程序，例如小型用户定义函数（头文件、.c 文件）