From c46f78d88e1f520bac00c29aa4a5025307393a8c Mon Sep 17 00:00:00 2001
From: Asklv <boironic@gmail.com>
Date: Fri, 27 Feb 2026 16:00:00 +0800
Subject: [PATCH] docs: add USB(JTAG) vs UART port guide for REPL usage

Add a detailed section to all three READMEs (EN, CN, JA) explaining
the difference between the USB (JTAG) and UART (COM) ports on
ESP32-S3 boards. Clarifies that the REPL CLI requires the UART port
and documents behavior when both ports are connected simultaneously.

Signed-off-by: Asklv <boironic@gmail.com>
---
 README.md    | 29 +++++++++++++++++++++++++++++
 README_CN.md | 29 +++++++++++++++++++++++++++++
 README_JA.md | 29 +++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+)

diff --git a/README.md b/README.md
index 2cda8cc..0db409f 100644
--- a/README.md
+++ b/README.md
@@ -191,6 +191,35 @@ mimi> cron_start                  # start cron scheduler now
 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:
+
+| 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` |
+
+> **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.
+
+**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`
+
+**Recommended workflow:**
+
+```bash
+# Flash via USB (JTAG) port
+idf.py -p /dev/cu.usbmodem11401 flash
+
+# Open REPL via UART (COM) port
+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 368104a..7a41802 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -206,6 +206,35 @@ mimi> cron_start                  # 立即启动 cron 调度器
 mimi> restart                     # 重启
 ```
 
+### USB (JTAG) 与 UART：哪个口做什么
+
+大多数 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` |
+
+> **使用 REPL 命令行必须连接 UART（COM）口**，而不是 USB（JTAG）口。ESP-IDF 控制台默认配置为 UART 输出（`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`）。USB（JTAG）口提供辅助串口输出，但不能可靠地支持交互式 REPL 输入。
+
+**同时连接两个口时：**
+
+- USB（JTAG）口负责烧录/下载，并提供辅助串口输出
+- UART（COM）口提供主要的交互式控制台，用于 REPL
+- macOS 下两个口都会显示为 `/dev/cu.usbmodem*` 或 `/dev/cu.usbserial-*`，用 `ls /dev/cu.usb*` 区分
+- Linux 下 USB（JTAG）通常是 `/dev/ttyACM0`，UART 通常是 `/dev/ttyUSB0`
+
+**推荐工作流：**
+
+```bash
+# 通过 USB（JTAG）口烧录
+idf.py -p /dev/cu.usbmodem11401 flash
+
+# 通过 UART（COM）口打开 REPL
+idf.py -p /dev/cu.usbserial-110 monitor
+# 或使用任意串口工具：screen、minicom、PuTTY，波特率 115200
+```
+
 ## 记忆
 
 MimiClaw 把所有数据存为纯文本文件，可以直接读取和编辑：
diff --git a/README_JA.md b/README_JA.md
index 8a12133..2b44e27 100644
--- a/README_JA.md
+++ b/README_JA.md
@@ -191,6 +191,35 @@ mimi> cron_start                  # cronスケジューラを今すぐ開始
 mimi> restart                     # 再起動
 ```
 
+### USB（JTAG）vs UART：どのポートで何をするか
+
+ほとんどの 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` |
+
+> **REPL CLIを使用するには、UART（COM）ポートに接続する必要があります。**USB（JTAG）ポートではありません。ESP-IDFコンソールはデフォルトでUART出力に設定されています（`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`）。USB（JTAG）ポートは補助的なシリアル出力を提供しますが、対話的なREPL入力を確実にサポートしません。
+
+**両方のポートを同時に接続している場合：**
+
+- USB（JTAG）ポートはフラッシュ/ダウンロードを処理し、補助シリアル出力を提供
+- UART（COM）ポートはREPL用のメインインタラクティブコンソールを提供
+- macOS では両ポートとも `/dev/cu.usbmodem*` または `/dev/cu.usbserial-*` として表示 — `ls /dev/cu.usb*` で確認
+- Linux では USB（JTAG）は通常 `/dev/ttyACM0`、UART は通常 `/dev/ttyUSB0`
+
+**推奨ワークフロー：**
+
+```bash
+# USB（JTAG）ポートでフラッシュ
+idf.py -p /dev/cu.usbmodem11401 flash
+
+# UART（COM）ポートでREPLを開く
+idf.py -p /dev/cu.usbserial-110 monitor
+# または任意のシリアルターミナル：screen、minicom、PuTTY（ボーレート 115200）
+```
+
 ## メモリ
 
 MimiClawはすべてのデータをプレーンテキストファイルとして保存します。直接読み取り・編集可能です：