From 3d806541f7461d0fc0b8f90643d09456a7800798 Mon Sep 17 00:00:00 2001 From: crispyberry Date: Sat, 28 Feb 2026 02:20:41 +0800 Subject: [PATCH] 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
collapse. Co-Authored-By: Claude Opus 4.6 --- README.md | 32 ++++++++++++++++++++++---------- README_CN.md | 24 ++++++++++++++++++------ README_JA.md | 24 ++++++++++++++++++------ 3 files changed, 58 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 0db409f..d8402b1 100644 --- a/README.md +++ b/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. + +
+Port details & recommended workflow + +| 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 ``` +
+ ## Memory MimiClaw stores everything as plain text files you can read and edit: diff --git a/README_CN.md b/README_CN.md index 7a41802..d8182ae 100644 --- a/README_CN.md +++ b/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 输入。 + +
+端口详情与推荐工作流 + +| 端口 | 标注 | 协议 | +|------|------|------| +| **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 ``` +
+ ## 记忆 MimiClaw 把所有数据存为纯文本文件，可以直接读取和编辑： diff --git a/README_JA.md b/README_JA.md index 2b44e27..42528ae 100644 --- a/README_JA.md +++ b/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入力をサポートしません。 + +
+ポート詳細と推奨ワークフロー + +| ポート | ラベル | プロトコル | +|--------|--------|------------| +| **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） ``` +
+ ## メモリ MimiClawはすべてのデータをプレーンテキストファイルとして保存します。直接読み取り・編集可能です：