Raft CLI (命令行界面)

注意：安装使用 'cargo install raftcli'，而不是侧边栏中列出的方式 见以下安装部分

Raft 是为 Espressif ESP32 系列嵌入式应用程序开发而设计的有观点的框架 - 更多关于 Raft 的信息，请见 此处

此命令行应用程序用于构建、构建、烧录和监控 raft 应用程序。

• 安装
• 创建新的 raft 应用程序
• 构建 raft 应用程序
• 将固件烧录到开发板上
• 监控串行端口
• 搭建问题

安装

使用在线服务 crates.io (raftcli 是用 Rust 编程语言编写的应用程序) 安装是最简单的方法，但如果你需要，也可以从源代码构建。

首先安装 Rust（既然你在这里，我假设你对嵌入式开发感兴趣，无论如何 Rust 可能是你的未来），按照以下步骤 安装 rust

然后使用以下命令安装应用程序

cargo install raftcli

如果你使用的是 Linux 操作系统并且遇到问题，请确保已安装以下系统依赖项

sudo apt-get update
sudo apt-get install pkg-config libudev-dev

还需要在你的系统上安装一些其他东西以支持构建和烧录 raft 应用程序

使用 Docker 构建

构建 raft 应用程序默认选项是使用 Docker，所以如果你还没有安装，请继续安装。

在这个场景中，你还需要一种方法来刷写ESP32系列芯片。最简单的方法是使用Python的pip包。请确保首先安装了Python和pip（在Windows上，你可以使用python3 -m pip --version或python -m pip --version）。如果pip没有安装，请安装python和pip。使用以下命令安装esptool：

python3 -m pip install esptool

注意：在Windows上，将python3改为python。

使用ESP IDF构建

或者，你可以安装Espressif ESP IDF。请确保所有要求都已正确安装，因为我发现Espressif的安装文档有些不清楚。另外，如果你从GitHub的发布页面安装ESP IDF，确保切换到ESP IDF文件夹并运行./install.sh或类似命令（在不同的操作系统上）——参见安装脚本。

你还需要确保在安装了IDF环境的shell中运行raft命令行界面程序。在linux/mac上，你可以使用如. ~/esp/esp-idf-v5.2.2\export.sh或类似的命令，具体取决于esp idf的安装位置和版本。另一个选项，也是Windows上可以使用的方法，是使用Espressif VS Code扩展，该扩展为你处理shell环境。否则，在Windows上和根据你安装的ESP IDF方式，你可能需要使用一个运行ESP IDF shell的快捷方式。

在这种情况下，使用-d选项，即raft run -d或raft build -d来禁用Docker的使用。

创建新的 raft 应用程序

$ raft new .

这将创建当前文件夹中的新raft应用程序。

你将需要回答一系列问题，包括你的应用程序名称、目标芯片等。有关问题的详细信息以及它们的含义，请参阅下面的“构建问题”部分

如果你想在不同的文件夹中构建应用程序，则在上面的命令行中将点（.）替换为你的选择文件夹。请注意，应用程序将直接创建在该文件夹中（而不是在子文件夹中），因此如果你想将应用程序放在名为./dev/MyRustApp的文件夹中，你必须指定此完整路径。

完成后，你将有一个类似这样的文件夹结构

├───components
│   └───MySysMod
├───main
└───systypes
    ├───Common
    │   ├───FSImage
    │   └───WebUI
    └───SysTypeMain

还有其他选项可用...

Create a new raft app

Usage: raft new [OPTIONS] [BASE_FOLDER]

Arguments:
  [BASE_FOLDER]

Options:
  -c, --clean  Clean the target folder
  -h, --help   Print help

构建 raft 应用程序

要构建现有的raft应用程序，请使用

raft build

这将使用Docker在当前文件夹中构建raft应用程序。如果你的raft应用程序有多个SysTypes，则可以使用-s选项定义要构建的SysType。

如果你不想在构建时使用Docker，则可以使用-d选项，在这种情况下，你需要确保系统上存在正确安装的ESP IDF（Espressif的开发环境）。你可以使用-i选项覆盖此ESP IDF的位置。

要执行清洁构建，请使用-c选项。

Build a raft app

Usage: raft build [OPTIONS] [APP_FOLDER]

Arguments:
  [APP_FOLDER]

Options:
  -s, --sys-type <SYS_TYPE>  System type to build
  -c, --clean                Clean the target folder
  -d, --no-docker            Don't use docker for build
  -i, --idf-path <IDF_PATH>  Full path to idf.py (when not using docker)
  -h, --help                 Print help

将固件刷写到开发板上

要编程开发板，请使用

raft run

这将首先构建固件（所有构建选项如上所述），然后将其刷写到Espressif处理器上，然后启动串行监视器。

要指定要使用的串行端口，请使用-p选项。你还可以使用-f选项指定刷写时的波特率。这个程序通常使用espressif esptool来执行实际的刷写工作。如果你需要指定此工具的完整路径，请使用-t选项。

固件更新过程完成后，将启动监控功能以查看串行端口输出。以下描述了这些选项，并且可以用于运行和监控命令。

要退出串行监控，请按 ESC。

Build, flash and monitor a raft app

Usage: raft run [OPTIONS] [APP_FOLDER]

Arguments:
  [APP_FOLDER]

Options:
  -s, --sys-type <SYS_TYPE>          System type to build
  -c, --clean                        Clean the target folder
  -d, --no-docker                    Don't use docker for build
  -i, --idf-path <IDF_PATH>          Full path to idf.py (when not using docker)
  -p, --port <PORT>                  Serial port
  -b, --monitor-baud <MONITOR_BAUD>  Monitor baud rate
  -r, --no-reconnect                 Disable serial port reconnection when monitoring
  -n, --native-serial-port           Native serial port when in WSL
  -f, --flash-baud <FLASH_BAUD>      Flash baud rate
  -t, --flash-tool <FLASH_TOOL>      Flash tool (e.g. esptool)
  -l, --log                          Log serial data to file
  -g, --log-folder <LOG_FOLDER>      Folder for log files [default: ./logs]
  -h, --help                         Print help

监控串行端口

raft monitor

这会启动串行监控，显示从设备接收到的串行输出，并将键盘命令发送到设备。要指定串行端口，请使用 -p 选项；要指定监控的波特率，请使用 -b。

可以使用 -l 选项启用接收到的串行数据的记录。这在调试时非常有用，因为它会自动以开始日期和时间命名日志文件，并在开发固件时提供测试运行的记录。通常使用 ./logs 文件夹来存储日志文件，但可以使用 -g 选项进行更改。

-r 选项用于在串行监控期间抑制串行端口的自动重新连接。通常，即使开发板被断开连接，串行监控器也会继续运行。这使得开发变得更加容易，因为经常需要重置或断开发发板，每次都重新启动串行监控器是一种麻烦。但如果需要，可以指定 -r 选项来禁用重新连接。

-n 选项仅在使用 Windows Subsystem for Linux (WSL) 时相关。使用 WSL 的正常行为是使用 raftcli 的 Windows 版本来进行固件更新和串行监控。这是因为 WSL（特别是 WSL2）不支持 USB 串行端口与主机操作系统共享。指定 -n 将导致 raftcli 使用 Linux 来访问串行端口。这仅在您使用类似 (USBIPD) 的工具时才会工作https://github.com/dorssel/usbipd-win。

Monitor a serial port

Usage: raft monitor [OPTIONS]

Options:
  -p, --port <PORT>                  Serial port
  -b, --monitor-baud <MONITOR_BAUD>  Baud rate
  -r, --no-reconnect                 Disable serial port reconnection when monitoring
  -n, --native-serial-port           Native serial port when in WSL
  -l, --log                          Log serial data to file
  -g, --log-folder <LOG_FOLDER>      Folder for log files [default: ./logs]
  -h, --help                         Print help

要退出串行监控，请按 ESC。

从源代码构建

如果您想从源代码构建此应用程序，则首先安装 rust。

克隆仓库

git clone https://github.com/robdobsn/RaftCLI
cd RaftCLI
cargo install --path .

这将在 cargo 使用的二进制可执行文件文件夹中构建和安装应用程序。

搭建问题

以下问题用于从模板文件完成脚手架

模板应用详情

使用raft_templates文件夹中的模板信息“scaffold”新的raft应用。

使用handlebars模板库根据运行“raft new”时提出的问题的答案填充模板中的空白。

除了生成源代码之外，还生成了针对各种构建场景的构建文件，包括

• 在Linux上本地构建
• 在mac、Linux和Windows上使用Docker构建

构建raft应用程序的最佳方式取决于您的操作系统和需求。我主要使用一台Windows机器，并在WSL中安装了Ubuntu（如果您不熟悉使用Windows Subsystem for Linux运行Linux，请搜索此信息）。我发现这是速度和便利性的最佳组合，并且该应用程序生成的Makefile在从WSL提示符运行时在该场景中表现良好。