docs: simplify UART/JTAG port section with collapsible details
Keep the essential port-to-use-case table and REPL warning visible, move protocol details and workflow commands into <details> collapse. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
crispyberry
32
README.md
32
README.md
@@ -193,21 +193,31 @@ mimi> restart # reboot
|
||||
|
||||
### USB (JTAG) vs UART: Which Port for What
|
||||
|
||||
Most ESP32-S3 dev boards expose **two USB-C ports**. Understanding which to use is critical:
|
||||
Most ESP32-S3 dev boards expose **two USB-C ports**:
|
||||
|
||||
| Port | Label | Protocol | Use for |
|
||||
|------|-------|----------|---------|
|
||||
| **USB** | USB / JTAG | Native USB Serial/JTAG | `idf.py flash`, `idf.py monitor`, JTAG debugging |
|
||||
| **COM** | UART / COM | External UART bridge (CP2102/CH340) | **REPL CLI**, serial console, `idf.py monitor` |
|
||||
| Port | Use for |
|
||||
|------|---------|
|
||||
| **USB** (JTAG) | `idf.py flash`, JTAG debugging |
|
||||
| **COM** (UART) | **REPL CLI**, serial console |
|
||||
|
||||
> **To use the REPL CLI, you must connect via the UART (COM) port**, not the USB (JTAG) port. The ESP-IDF console/REPL is configured to use UART by default (`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`). The USB (JTAG) port provides secondary console output but does not support interactive REPL input reliably.
|
||||
> **REPL requires the UART (COM) port.** The USB (JTAG) port does not support interactive REPL input.
|
||||
|
||||
<details>
|
||||
<summary>Port details & recommended workflow</summary>
|
||||
|
||||
| Port | Label | Protocol |
|
||||
|------|-------|----------|
|
||||
| **USB** | USB / JTAG | Native USB Serial/JTAG |
|
||||
| **COM** | UART / COM | External UART bridge (CP2102/CH340) |
|
||||
|
||||
The ESP-IDF console/REPL is configured to use UART by default (`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`).
|
||||
|
||||
**If you have both ports connected simultaneously:**
|
||||
|
||||
- The USB (JTAG) port handles flash/download and provides a secondary serial output
|
||||
- The UART (COM) port provides the primary interactive console for the REPL
|
||||
- On macOS, both ports appear as `/dev/cu.usbmodem*` or `/dev/cu.usbserial-*` — check `ls /dev/cu.usb*` to identify them
|
||||
- On Linux, USB (JTAG) typically shows as `/dev/ttyACM0` and UART as `/dev/ttyUSB0`
|
||||
- USB (JTAG) handles flash/download and provides secondary serial output
|
||||
- UART (COM) provides the primary interactive console for the REPL
|
||||
- macOS: both appear as `/dev/cu.usbmodem*` or `/dev/cu.usbserial-*` — run `ls /dev/cu.usb*` to identify
|
||||
- Linux: USB (JTAG) → `/dev/ttyACM0`, UART → `/dev/ttyUSB0`
|
||||
|
||||
**Recommended workflow:**
|
||||
|
||||
@@ -220,6 +230,8 @@ idf.py -p /dev/cu.usbserial-110 monitor
|
||||
# or use any serial terminal: screen, minicom, PuTTY at 115200 baud
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Memory
|
||||
|
||||
MimiClaw stores everything as plain text files you can read and edit:
|
||||
|
||||
24
README_CN.md
24
README_CN.md
@@ -208,14 +208,24 @@ mimi> restart # 重启
|
||||
|
||||
### USB (JTAG) 与 UART：哪个口做什么
|
||||
|
||||
大多数 ESP32-S3 开发板有 **两个 USB-C 口**，务必区分清楚：
|
||||
大多数 ESP32-S3 开发板有 **两个 USB-C 口**：
|
||||
|
||||
| 端口 | 标注 | 协议 | 用途 |
|
||||
|------|------|------|------|
|
||||
| **USB** | USB / JTAG | 原生 USB Serial/JTAG | `idf.py flash`、`idf.py monitor`、JTAG 调试 |
|
||||
| **COM** | UART / COM | 外置 UART 桥接芯片（CP2102/CH340） | **REPL 命令行**、串口控制台、`idf.py monitor` |
|
||||
| 端口 | 用途 |
|
||||
|------|------|
|
||||
| **USB**（JTAG） | `idf.py flash`、JTAG 调试 |
|
||||
| **COM**（UART） | **REPL 命令行**、串口控制台 |
|
||||
|
||||
> **使用 REPL 命令行必须连接 UART（COM）口**，而不是 USB（JTAG）口。ESP-IDF 控制台默认配置为 UART 输出（`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`）。USB（JTAG）口提供辅助串口输出，但不能可靠地支持交互式 REPL 输入。
|
||||
> **REPL 必须连接 UART（COM）口。** USB（JTAG）口不支持交互式 REPL 输入。
|
||||
|
||||
<details>
|
||||
<summary>端口详情与推荐工作流</summary>
|
||||
|
||||
| 端口 | 标注 | 协议 |
|
||||
|------|------|------|
|
||||
| **USB** | USB / JTAG | 原生 USB Serial/JTAG |
|
||||
| **COM** | UART / COM | 外置 UART 桥接芯片（CP2102/CH340） |
|
||||
|
||||
ESP-IDF 控制台默认配置为 UART 输出（`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`）。
|
||||
|
||||
**同时连接两个口时：**
|
||||
|
||||
@@ -235,6 +245,8 @@ idf.py -p /dev/cu.usbserial-110 monitor
|
||||
# 或使用任意串口工具：screen、minicom、PuTTY，波特率 115200
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 记忆
|
||||
|
||||
MimiClaw 把所有数据存为纯文本文件，可以直接读取和编辑：
|
||||
|
||||
24
README_JA.md
24
README_JA.md
@@ -193,14 +193,24 @@ mimi> restart # 再起動
|
||||
|
||||
### USB（JTAG）vs UART：どのポートで何をするか
|
||||
|
||||
ほとんどの ESP32-S3 開発ボードには **2つの USB-C ポート**があります。用途を正しく理解することが重要です：
|
||||
ほとんどの ESP32-S3 開発ボードには **2つの USB-C ポート**があります：
|
||||
|
||||
| ポート | ラベル | プロトコル | 用途 |
|
||||
|--------|--------|------------|------|
|
||||
| **USB** | USB / JTAG | ネイティブ USB Serial/JTAG | `idf.py flash`、`idf.py monitor`、JTAGデバッグ |
|
||||
| **COM** | UART / COM | 外部 UART ブリッジ（CP2102/CH340） | **REPL CLI**、シリアルコンソール、`idf.py monitor` |
|
||||
| ポート | 用途 |
|
||||
|--------|------|
|
||||
| **USB**（JTAG） | `idf.py flash`、JTAGデバッグ |
|
||||
| **COM**（UART） | **REPL CLI**、シリアルコンソール |
|
||||
|
||||
> **REPL CLIを使用するには、UART（COM）ポートに接続する必要があります。**USB（JTAG）ポートではありません。ESP-IDFコンソールはデフォルトでUART出力に設定されています（`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`）。USB（JTAG）ポートは補助的なシリアル出力を提供しますが、対話的なREPL入力を確実にサポートしません。
|
||||
> **REPLにはUART（COM）ポートが必要です。** USB（JTAG）ポートは対話的なREPL入力をサポートしません。
|
||||
|
||||
<details>
|
||||
<summary>ポート詳細と推奨ワークフロー</summary>
|
||||
|
||||
| ポート | ラベル | プロトコル |
|
||||
|--------|--------|------------|
|
||||
| **USB** | USB / JTAG | ネイティブ USB Serial/JTAG |
|
||||
| **COM** | UART / COM | 外部 UART ブリッジ（CP2102/CH340） |
|
||||
|
||||
ESP-IDFコンソールはデフォルトでUART出力に設定されています（`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`）。
|
||||
|
||||
**両方のポートを同時に接続している場合：**
|
||||
|
||||
@@ -220,6 +230,8 @@ idf.py -p /dev/cu.usbserial-110 monitor
|
||||
# または任意のシリアルターミナル：screen、minicom、PuTTY（ボーレート 115200）
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## メモリ
|
||||
|
||||
MimiClawはすべてのデータをプレーンテキストファイルとして保存します。直接読み取り・編集可能です：
|
||||
|
||||
Reference in New Issue
Block a user