# ESP-WSL

**Repository Path**: freechful/esp-wsl

## Basic Information

- **Project Name**: ESP-WSL
- **Description**: 在WSL中进行ESP32开发，使用Windwos下的IDF工具进行下载和监控，避免USB设备的挂载问题
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-07
- **Last Updated**: 2025-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 ESP Flash Tool

一个专为 WSL (Windows Subsystem for Linux) 环境设计的 ESP32 开发工具 VS Code 扩展。

## 💡 解决什么问题？

在 WSL 中开发 ESP32 时，USB 设备挂载复杂且不稳定。本扩展提供完美解决方案：
- **📝 开发编译**：在 WSL 中享受 Linux 开发环境
- **🔥 烧录监控**：使用 Windows ESP-IDF 工具，稳定可靠
- **🔄 无缝切换**：一键操作，自动处理路径转换

## 功能特色

- 🔥 **一键烧录**: 自动检测 ESP32 项目的二进制文件并烧录到设备
- 📡 **串口监控**: 实时监控 ESP32 设备的串口输出，支持调试符号解析
- ⚙️ **智能配置**: 向导式配置 ESP-IDF 环境和工具链
- 🎯 **芯片支持**: 支持所有主流 ESP32 芯片 (ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C6, ESP32-H2)
- 🖥️ **WSL 优化**: 专为 WSL 环境优化，完美兼容 Windows ESP-IDF 工具链

## 工作流程

- **开发编译**: 在 WSL 中进行代码开发和编译
- **烧录监控**: 使用 Windows ESP-IDF 工具进行烧录和串口监控
- **调试支持**: 自动处理路径转换，支持堆栈跟踪和调试符号

## 快速开始

### 1. 前置要求

- Windows 10/11 with WSL2
- ESP-IDF 已安装在 Windows 环境中
- VS Code 安装在 Windows 系统上
- ESP32 开发板和 USB 连接线

### 2. 安装扩展

1. 打开 VS Code
2. 进入扩展市场 (Ctrl+Shift+X)
3. 搜索 "ESP Flash Tool"
4. 点击安装

### 3. 首次配置

扩展首次启动时会自动弹出配置向导：

1. **选择 ESP-IDF 路径**: 选择您的 ESP-IDF 安装目录
   - 例如: `E:\Espressif\esp525\Espressif\frameworks\esp-idf-v5.2.5`

2. **选择 Python 环境**: 选择 ESP-IDF 的 Python 环境目录
   - 例如: `E:\Espressif\esp525\Espressif\python_env\idf5.2_py3.11_env`

3. **选择 COM 端口**: 选择 ESP32 设备连接的串口

4. **选择芯片类型**: 选择您使用的 ESP32 芯片型号

## 使用方法

### 状态栏按钮

扩展会在 VS Code 状态栏添加以下按钮：

- 🔥 **ESP烧录**: 一键烧录当前项目
- 🔌 **COM端口**: 显示当前端口，点击可切换
- 📺 **ESP监控**: 启动/停止串口监控

### 烧录设备

1. 确保您的 ESP32 项目已编译（在 WSL 中运行 `idf.py build`）
2. 连接 ESP32 设备到电脑
3. 点击状态栏的 "ESP烧录" 按钮
4. 扩展会自动检测并烧录以下文件：
   - `build/bootloader/bootloader.bin` (地址: 0x0)
   - `build/partition_table/partition-table.bin` (地址: 0x15000)
   - `build/*.bin` 主应用程序 (地址: 0x20000)

### 串口监控

1. 点击状态栏的 "ESP监控" 按钮
2. 扩展会自动：
   - 检测并复制 ELF 调试文件到 Windows 临时目录
   - 设置工具链路径
   - 启动 idf_monitor.py
3. 实时查看设备输出，包括：
   - 程序日志输出
   - 错误信息和堆栈跟踪
   - 自动符号解析（显示源代码行号）

**监控控制**:
- `Ctrl+]`: 退出监控
- `Ctrl+T`: 显示菜单
- `Ctrl+T` → `Ctrl+H`: 显示帮助

### 端口管理

1. 点击状态栏的端口按钮（如 "COM5"）
2. 从下拉列表中选择新的端口
3. 端口设置会自动保存

## 配置选项

可通过 VS Code 设置 (Ctrl+,) 搜索 "esp-flash" 来修改以下配置：

| 配置项 | 描述 | 默认值 |
|--------|------|--------|
| `esp-flash.pythonPath` | Python 可执行文件路径 | - |
| `esp-flash.idfPath` | ESP-IDF 框架路径 | - |
| `esp-flash.port` | ESP32 串口 | COM5 |
| `esp-flash.baudRate` | 烧录波特率 | 460800 |
| `esp-flash.monitorBaudRate` | 串口监控波特率 | 115200 |
| `esp-flash.chip` | ESP32 芯片类型 | esp32c6 |
| `esp-flash.flashMode` | 烧录模式 | dio |
| `esp-flash.flashFreq` | 烧录频率 | 80m |
| `esp-flash.flashSize` | Flash 大小 | 4MB |

## 命令面板

可通过命令面板 (Ctrl+Shift+P) 使用以下命令：

- `ESP Flash: Flash Device` - 烧录设备
- `ESP Flash: Monitor Serial Port` - 串口监控
- `ESP Flash: Select COM Port` - 选择端口
- `ESP Flash: Configure Settings` - 配置设置

## 故障排除

### 烧录失败

1. **检查端口**: 确保选择了正确的 COM 端口
2. **检查连接**: 确保 USB 线缆正常连接
3. **检查驱动**: 确保已安装 ESP32 USB 驱动程序
4. **检查文件**: 确保项目已在 WSL 中成功编译

### 监控问题

1. **找不到调试文件**: 确保项目已编译生成 .elf 文件
2. **工具链错误**: 检查 ESP-IDF 安装是否完整
3. **权限问题**: 确保有权限访问 COM 端口

### 配置问题

1. **路径错误**: 使用配置向导重新设置路径
2. **Python 环境**: 确保选择的是 ESP-IDF 专用的 Python 环境
3. **重新配置**: 通过命令面板运行 "ESP Flash: Configure Settings"

## 技术原理

### WSL 集成

- 扩展运行在 WSL 环境中，可以直接访问 Linux 文件系统
- 烧录和监控命令在 Windows 终端中执行，确保硬件访问正常
- 自动处理 WSL 和 Windows 路径转换

### 文件处理

- ELF 调试文件自动从 WSL 复制到 Windows 临时目录
- 二进制文件路径自动转换为 Windows UNC 格式
- 临时文件在监控结束后自动清理

### 工具链检测

- 自动检测 ESP-IDF 工具链安装位置
- 动态设置 PATH 环境变量确保工具可用
- 支持多版本工具链自动选择

## 更新日志

### v0.0.1 (初始版本)

- 基础烧录功能
- 串口监控支持
- WSL 路径处理
- 配置向导
- 芯片支持
- 工具链自动检测

## 开发贡献

欢迎提交 Issues 和 Pull Requests！

### 开发环境

```bash
# 克隆项目
git clone https://gitee.com/freechful/esp-wsl.git
cd ESPFlash

# 安装依赖
npm install

# 编译
npm run compile

# 监听模式
npm run watch
```

## 许可证

MIT License

## 联系方式

如有问题或建议，请提交 Issue 或 Pull Request。

---

**注意**: 此扩展专为 WSL 环境设计，在纯 Windows 或 Linux 环境下可能需要额外配置。