Add IDF workflow how-to guide
Covers end-to-end ESP-IDF workflows: environment check, target setup, build, flash, monitor, and troubleshooting. Uses Starlight Steps/Tabs components for structured walkthroughs.
This commit is contained in:
parent
76ff1ad46a
commit
50fdfce73a
223
docs-site/src/content/docs/guides/idf-workflow.mdx
Normal file
223
docs-site/src/content/docs/guides/idf-workflow.mdx
Normal file
@ -0,0 +1,223 @@
|
||||
---
|
||||
title: IDF Project Workflows
|
||||
description: Build, flash, and monitor ESP-IDF projects through MCP tools
|
||||
sidebar:
|
||||
order: 8
|
||||
---
|
||||
|
||||
import { Steps, Aside, Tabs, TabItem, LinkCard } from '@astrojs/starlight/components';
|
||||
|
||||
mcesptool wraps ESP-IDF's toolchain management and project build system as MCP tools. This guide walks through the full development cycle: checking your environment, setting up toolchains for a target chip, building, flashing, and monitoring. Each section is self-contained -- jump to the step you need.
|
||||
|
||||
## Check your environment
|
||||
|
||||
Before building anything, confirm that ESP-IDF is detected and see which toolchains are installed.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Get the ESP-IDF path, version, and environment variables:
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_env_info", {})
|
||||
```
|
||||
|
||||
The response includes `idf_path`, `idf_version`, and the `PATH` additions that ESP-IDF exports. If `success` is `false`, ESP-IDF is not installed or not on the system path.
|
||||
|
||||
2. Check which tools are installed vs missing:
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_tools_check", {})
|
||||
```
|
||||
|
||||
The response lists every tool with its install status. The `installed_count` and `missing_count` fields give a quick summary.
|
||||
|
||||
</Steps>
|
||||
|
||||
<Aside type="tip">
|
||||
You can also read the `esp://idf/status` resource for a quick overview that includes per-target readiness without calling any tools.
|
||||
</Aside>
|
||||
|
||||
## Set up a new target chip
|
||||
|
||||
When you need to build for a chip you have not used before (say, an ESP32-P4), some toolchains may be missing. The RISC-V targets need the `riscv32-esp-elf` toolchain; Xtensa targets need `xtensa-esp-elf`.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Check readiness for the specific target:
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_tools_check", {
|
||||
"target": "esp32p4"
|
||||
})
|
||||
```
|
||||
|
||||
Look at the `target_ready` field. If it is `false`, the `missing_for_target` array tells you exactly which tools are needed.
|
||||
|
||||
2. Install the missing tools:
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_tools_install", {
|
||||
"targets": ["esp32p4"]
|
||||
})
|
||||
```
|
||||
|
||||
This downloads and installs only the tools required for the specified targets. You can pass multiple targets at once (e.g. `["esp32p4", "esp32c6"]`) to install everything in a single operation.
|
||||
|
||||
3. Verify the installation:
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_tools_check", {
|
||||
"target": "esp32p4"
|
||||
})
|
||||
# result["target_ready"] should now be true
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
<Aside type="caution">
|
||||
Toolchain downloads can be large -- 100MB or more per architecture. The install operation has a 10-minute timeout. On slow connections, install one target at a time.
|
||||
</Aside>
|
||||
|
||||
## Build a project
|
||||
|
||||
With the toolchain in place, build an ESP-IDF project for your target.
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_build_project", {
|
||||
"project_path": "/home/user/esp/my-project",
|
||||
"target": "esp32p4"
|
||||
})
|
||||
```
|
||||
|
||||
The `project_path` must point to a directory containing a `CMakeLists.txt`. The tool runs `idf.py set-target` followed by `idf.py build`.
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Incremental build">
|
||||
The default behavior is an incremental build. CMake only recompiles files that changed since the last build.
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_build_project", {
|
||||
"project_path": "/home/user/esp/my-project",
|
||||
"target": "esp32s3"
|
||||
})
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="Clean build">
|
||||
If you are switching targets or need to start fresh, set `clean` to `true`. This runs `idf.py fullclean` before building.
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_build_project", {
|
||||
"project_path": "/home/user/esp/my-project",
|
||||
"target": "esp32s3",
|
||||
"clean": True
|
||||
})
|
||||
```
|
||||
|
||||
A clean build is also useful when you see stale object files causing link errors after changing `sdkconfig` options.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Flash to device
|
||||
|
||||
Once the build completes, flash it to a connected device.
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_flash_project", {
|
||||
"project_path": "/home/user/esp/my-project",
|
||||
"port": "/dev/ttyUSB0"
|
||||
})
|
||||
```
|
||||
|
||||
The tool runs `idf.py flash` using the build artifacts already in the project's `build/` directory. It flashes the bootloader, partition table, and application binary in one operation.
|
||||
|
||||
<Aside type="tip">
|
||||
The default baud rate is 460800. If you experience frequent flash failures, drop to a lower rate:
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_flash_project", {
|
||||
"project_path": "/home/user/esp/my-project",
|
||||
"port": "/dev/ttyUSB0",
|
||||
"baud": 115200
|
||||
})
|
||||
```
|
||||
</Aside>
|
||||
|
||||
## Monitor output
|
||||
|
||||
After flashing, capture the device's serial output to verify it booted correctly.
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_monitor", {
|
||||
"port": "/dev/ttyUSB0",
|
||||
"duration": 15
|
||||
})
|
||||
```
|
||||
|
||||
The tool captures serial output for the specified duration (default 10 seconds, max 60) and returns it as text.
|
||||
|
||||
### ELF-based crash decoding
|
||||
|
||||
When you provide the `project_path`, IDF monitor uses the built ELF file to decode crash backtraces into source file names and line numbers.
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_monitor", {
|
||||
"port": "/dev/ttyUSB0",
|
||||
"project_path": "/home/user/esp/my-project",
|
||||
"duration": 20
|
||||
})
|
||||
```
|
||||
|
||||
Without `project_path`, backtrace addresses appear as raw hex values. With it, you get output like `app_main.c:42` instead of `0x400d1234`.
|
||||
|
||||
## Troubleshoot
|
||||
|
||||
### ESP-IDF not detected
|
||||
|
||||
If `idf_env_info` returns `success: false`, the IDF path is not set. Common causes:
|
||||
|
||||
- ESP-IDF is not installed. Follow the [ESP-IDF Get Started guide](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/) to install it.
|
||||
- The `IDF_PATH` environment variable is not set in the shell where the MCP server runs. Make sure `export.sh` (or `export.bat` on Windows) has been sourced before starting the server.
|
||||
|
||||
### Tier 2 tools report "environment not available"
|
||||
|
||||
The build, flash, and monitor tools require a fully configured IDF environment. If they fail with this error:
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Run `idf_tools_check` to see what is missing.
|
||||
|
||||
2. Run `idf_tools_install` with the appropriate targets.
|
||||
|
||||
3. Restart the MCP server so the updated PATH takes effect.
|
||||
|
||||
</Steps>
|
||||
|
||||
### Missing tools for a target
|
||||
|
||||
When `idf_tools_check` shows `target_ready: false`, the specific toolchain for that chip architecture is not installed. RISC-V targets (esp32c2, esp32c3, esp32c5, esp32c6, esp32c61, esp32h2, esp32p4) need `riscv32-esp-elf`. Xtensa targets (esp32, esp32s2, esp32s3) need `xtensa-esp-elf`. Run `idf_tools_install` with the target name and the correct toolchain is resolved automatically.
|
||||
|
||||
### Build failures after switching targets
|
||||
|
||||
If you change the `target` parameter without cleaning the build directory, CMake may fail with configuration errors. Use a clean build:
|
||||
|
||||
```python
|
||||
result = await client.call_tool("idf_build_project", {
|
||||
"project_path": "/home/user/esp/my-project",
|
||||
"target": "esp32c6",
|
||||
"clean": True
|
||||
})
|
||||
```
|
||||
|
||||
### Flash connection failures
|
||||
|
||||
If flashing fails with a connection timeout:
|
||||
|
||||
- Confirm the device is in download mode. Most dev boards enter download mode automatically, but some require holding the BOOT button during reset.
|
||||
- Check the serial port path. Use `esp_detect_ports` to list connected devices.
|
||||
- Try a lower baud rate. Long USB cables or cheap adapters may not sustain 460800 baud reliably.
|
||||
|
||||
<LinkCard
|
||||
title="IDF Integration Reference"
|
||||
description="Full parameter details for all IDF toolchain and project workflow tools."
|
||||
href="/reference/idf-integration/"
|
||||
/>
|
||||
Loading…
x
Reference in New Issue
Block a user