《Muse Gadgets 实战》第 6 章：第一次编译和刷机

前面两章把环境和 Token 都备齐了，这一章动真格：把 Muse Gadgets 固件刷进 ESP32。本章以 ESP32-C5 DevKitC-1 为例，从拉代码到刷机成功，完整走一遍。

第 4 章装好的 ESP-IDF v6.0.1 和第 5 章领的 SDK Token，现在都用得上。

动手前先确认两件事

第一，ESP-IDF 环境要在当前终端生效。

官方 README 特别提醒：每个新终端都要跑一遍 export.sh。

~/esp/esp-idf-v6/export.sh

忘跑这个，后面 idf.py 命令直接报找不到。

第二，数据线别拿错。

官方要求是"a USB cable that carries data"——带数据的线，不是只能充电的那根。拿根只能充电的线，刷机时串口死活不出来，浪费半天。

拉代码，进 esp32 目录

打开终端：

g
i
t
 
c
l
o
n
e
 
h
t
t
p
s
:
/
/
g
i
t
h
u
b
.
c
o
m
/
f
a
c
e
b
o
o
k
i
n
c
u
b
a
t
o
r
/
m
u
s
e
-
g
a
d
g
e
t
-
s
d
k


c
d
 
m
u
s
e
-
g
a
d
g
e
t
-
s
d
k
/
e
s
p
3
2

注意进的是 esp32 子目录，后面所有编译刷机命令都在这里跑。

2026-10-13 实测：仓库未归档，star 数 2060，最后一次推送是 2026-10-12。来源：GitHub 仓库页。

menuconfig 填 Token，然后编译

Token 在第 5 章领的那个。编译前必须先塞进去，不然固件连不上云服务：

i
d
f
.
p
y
 
m
e
n
u
c
o
n
f
i
g

菜单里找 ESP32 Device SDK > Muse Gadgets SDK token。把 Token 粘贴进去，保存退出。

（2026-10-13 实测，来源 esp32/README.md"### 2. Build"）

然后编译：

i
d
f
.
p
y
 
b
u
i
l
d

编译成功，固件在 build/muse-gadget.bin。

多说一句：ESP32-C5 DevKitC-1 是官方默认板，直接 idf.py build 就行，不用额外配置。其他板才走 tools/board.sh。来源：esp32/README.md 板子表第一行。

串口怎么找

刷机得指定串口，不同系统找法不一样。

macOS：

l
s
 
/
d
e
v
/
c
u
.
u
s
b
*

一般能看到 /dev/cu.usbmodemXXXX，XXXX 换成你看到的实际数字。

Linux：

看 /dev/ttyACM* 或 /dev/ttyUSB*。

Windows 怎么找 COM 口？

打开设备管理器，"端口（COM 和 LPT）"下面找对应的 COM 口，比如 COM3。这是常规操作。

来源：macOS/Linux 找法 2026-10-13 实测，来源 esp32/README.md"### 3. Flash"。

【购买链接待补：ESP32-C5 开发板】

一条命令刷机

插好板子，执行：

i
d
f
.
p
y
 
-
p
 
/
d
e
v
/
c
u
.
u
s
b
m
o
d
e
m
1
1
0
1
 
f
l
a
s
h
 
m
o
n
i
t
o
r

/dev/cu.usbmodem1101 是示例，换成你自己的串口。monitor 会实时输出设备日志，想退出按 Ctrl + ]。

刷完灯呼吸橙色，说明成功了——这表示板子在等配对，配对流程第 7 章讲。

刷机失败怎么办

日志报错、大概率连不上，按这个手动进下载模式：

1. 按住板子上的 BOOT 键不松

2. 点一下 RESET 键

3. 松开 BOOT

4. 重跑刷机命令

这招 2026-10-13 实测，来源 esp32/README.md"### 3. Flash"原文。

Windows 能刷吗

说实话，官方 README 只写了 macOS 或 Linux。Windows 下跑通这条刷机命令，待验证。

建议优先用 Mac 或 Linux。Windows 用户要么看第 4 章的 Linux 子系统路线，要么等有实测结论后再跟进。不确定的事不写死。

重刷会丢数据吗

不会。官方明确写了：reflashing keeps your pairing and Wi-Fi settings。重刷固件，配对信息和 Wi-Fi 密码都在。

想彻底清空、从零开始，刷之前先跑：

i
d
f
.
p
y
 
-
p
 
你
的
串
口
 
e
r
a
s
e
-
f
l
a
s
h

让 AI 代劳？

不想敲命令，可以用 Muse Code：

c
u
r
l
 
-
f
s
S
L
 
h
t
t
p
s
:
/
/
d
e
v
.
m
e
t
a
.
a
i
/
i
n
s
t
a
l
l
.
s
h
 
|
 
s
h

装好后进 esp32 目录，让它读 AGENTS.md，自己会搭工具链、编译、刷机。本章以手动为主，目的是让你理解底层逻辑——工具迟早会变，流程不会。

事实核实声明

– 仓库地址、star 2060、未归档、最后推送 2026-10-12：2026-10-13 实测，来源 GitHub 仓库页。

– ESP-IDF 版本限定 v6.0.1：2026-10-13 实测，来源 esp32/README.md"### 1. Install ESP-IDF v6.0.1"。

– 每个新终端都要跑 export.sh：2026-10-13 实测，来源 esp32/README.md 原文"Run the last line in every new terminal you build from"。

– 数据线要求（带数据传输能力）：2026-10-13 实测，来源 esp32/README.md"What you need"。

– clone 命令、esp32 子目录、ESP32-C5 默认板直接 idf.py build：2026-10-13 实测，来源 esp32/README.md"### 2. Build"及板子表。

– menuconfig 路径（ESP32 Device SDK > Muse Gadgets SDK token）、固件位置 build/muse-gadget.bin：2026-10-13 实测，来源 esp32/README.md"### 2. Build"。

– **刷机命令、串口查找（macOS /dev/cu.usb\*、Linux /dev/ttyACM\*/ttyUSB\*）、BOOT+RESET 进下载模式、Ctrl-] 退出 monitor**：2026-10-13 实测，来源 esp32/README.md"### 3. Flash"。

– 重刷保留配对和 Wi-Fi、erase-flash 彻底清空：2026-10-13 实测，来源 esp32/README.md"### 3. Flash"。

– 电脑系统要求（macOS 或 Linux）：2026-10-13 实测，来源 esp32/README.md"What you need"。Windows 刷机可行性：待验证。

《Muse Gadgets 实战》第 6 章：第一次编译和刷机

《Muse Gadgets 实战》第 6 章：第一次编译和刷机

动手前先确认两件事

拉代码，进 esp32 目录

menuconfig 填 Token，然后编译

串口怎么找

一条命令刷机

刷机失败怎么办

Windows 能刷吗

重刷会丢数据吗

让 AI 代劳？

事实核实声明

相关章节