docs: align T153MX Linux tutorial workflow

Author: codebug8

docs/T153MX/01-BoardIntroduction.md

@@ -16,29 +16,6 @@ OmniGate-T153 是一款基于全志 T153MX 的工业边缘网关开发板，由
 
 :::
 
-## 目标
-
-通过本页确认 OmniGate-T153 的核心板、扩展底板、主要接口和软件支持状态，并找到从获取板级 overlay 到首次进入 Linux Shell 的最短路径。
-
-## 准备工作
-
-- OmniGate-T153 开发板及对应批次的原理图、BOM 或硬件说明。
-- 稳定电源、USB 数据线和调试串口连接。
-- Ubuntu 开发主机及可用的 T153 Tina SDK。
-
-不同批次的内存、eMMC、无线和 4G 模块可能不同。开始实验前应以实物和当前批次资料核对，不能只根据同系列板卡推断。
-
-## 操作步骤
-
-1. 查看下方产品组成和资源表，确认核心板与底板版本。
-2. 克隆板级适配仓库，将 overlay 应用到完整 Tina SDK。
-3. 选择 `t153_omnigate_mmc-buildroot`，完成编译和打包。
-4. 核对镜像路径和目标设备后烧录，通过调试串口观察首次启动。
-
-## 验证方法
-
-启动后应能从串口进入开发板 Linux Shell。使用 `uname -a`、`cat /proc/partitions` 和对应接口的设备节点确认运行内核、存储与板级配置；未完成板端验证的功能仍以本页状态表为准。
-
 ## 产品组成
 
 ### mCore-T153MX 核心板
@@ -125,96 +102,23 @@ flowchart TB
 | 功能 | 当前状态 | 说明 |
 | --- | --- | --- |
 | 双千兆以太网 | 已配置 | `gmac0`、`gmac1` 及对应 PHY 已在设备树启用 |
-| CAN FD | 已配置 | `can0`、`can1` 已配置 |
+| CAN FD | 驱动已配置，控制器默认关闭 | 内核已启用 CAN/CAN RAW；当前 `board.dts` 中 `can0`、`can1` 为 `disabled` |
 | Wi-Fi / Bluetooth | 已实板验证 | AIC8800D80，SDIO + UART |
 | Bluetooth PCM | 已实板验证 | I2S0 使用 PB5～PB8 |
 | eMMC / TF Card | 已配置 | 当前构建目标为 eMMC Buildroot 方案 |
 | MIPI DSI 4-Lane | 调试中 | 背光、初始化和 DRM 已工作，仍存在水平条纹 |
 | 双 4G | 硬件支持 | 需根据实际 4G 模块补充拨号和运营商配置 |
 | E907 AMP Shell | 已实板验证 | A7 Linux 通过 remoteproc、MSGBOX 和 RPMsg 连接 E907 FreeRTOS |
 
-“已配置”表示板级配置中已经启用相关控制器，不代表所有外接设备、线材和应用场景均完成验证。
-
-## 获取开发资料
-
-### 获取 T153MX 基础 SDK
-
-基础开发包通过百度网盘提供：
-
-- 文件夹：`DshanPI-OminiGate_T153MX`
-- 下载链接：[https://pan.baidu.com/s/1ai6yzYs5ujDba-luz-JeXw](https://pan.baidu.com/s/1ai6yzYs5ujDba-luz-JeXw)
-- 提取码：`6mtk`
-
-下载完成后，先阅读[Tina SDK 开发环境搭建](./part3/01-DevelopmentEnvironmentSetup.md)。网盘文件夹名称不等于解压后的 SDK 根目录；能够看到 `build/envsetup.sh`、`build.sh`、`device/`、`kernel/` 和 `buildroot/` 的目录才是 SDK 根目录。
-
-:::tip 建议保留原始包
-
-首次解压后不要直接覆盖唯一副本。建议保留一份未修改的基础 SDK，用于比对板级修改、恢复误删文件和重新生成 overlay 补丁。
-
-:::
-
-### 获取 OmniGate 板级适配仓库
-
-```bash
-git clone https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate.git
-```
-
-仓库采用 overlay 结构，主要内容如下：
-
-```text
-T153MX-Tina5SDK_OmniGate/
-├── docs/       单板说明与专题调试记录
-├── images/     核心板和扩展底板图片
-├── overlay/    按 Tina SDK 根目录组织的差异文件
-├── meta/       差异、删除和状态记录
-└── scripts/    应用 overlay 和执行删除的脚本
-```
-
-## 应用板级配置
-
-假设 Tina SDK 位于 `/path/to/TinaSDK`，执行：
-
-```bash
-/path/to/T153MX-Tina5SDK_OmniGate/scripts/apply_overlay.sh /path/to/TinaSDK
-```
-
-该脚本只会将 `overlay/` 中的文件覆盖到 SDK 对应路径，不会自动执行删除操作。需要清理旧固件时，应先人工检查 `meta/delete_list.txt`，确认无误后再运行仓库提供的删除脚本。
-
-## 编译与打包
-
-完整的主机依赖、SDK 检查、编译和产物验证步骤见[Tina SDK 开发环境搭建](./part3/01-DevelopmentEnvironmentSetup.md)。下面仅列出已经配置好环境后的最短命令。
-
-在已经应用 overlay 的 Tina SDK 根目录，首次先执行交互式方案配置：
-
-```bash
-source build/envsetup.sh
-./build.sh config
-```
-
-按名称选择 `linux`、`buildroot`、`t153`、`omnigate`、`default` 和 `linux-5.10-origin`，该组合
-对应 `t153_omnigate_mmc-buildroot`。随后执行：
-
-```bash
-./build.sh
-./build.sh pack
-```
-
-当前镜像输出名称：
-
-```text
-out/t153/omnigate/buildroot/t153_linux_omnigate_uart0.img
-```
-
-启用对应无线配置时，也可能生成 `t153_linux_omnigate_uart0-wifi1.img`。烧录前必须根据本次 `pack` 的时间戳和构建配置选择镜像，不能只按文件名猜测。
+“已配置”表示 SDK 中已经包含对应驱动或板级配置，不代表当前镜像已启用控制器，也不代表所有外接设备、线材和应用场景均完成验证。
 
-烧录和串口调试前请确认目标设备、USB 连接和镜像路径，避免误写其他存储设备。
+## 接下来做什么
 
-## 调试资料
+单板介绍只用于认识硬件，不在这里展开 SDK 和烧录操作。第一次使用建议按以下顺序继续：
 
-- [板载功能体验](./part2/01-Ethernet.md)
-- [HelloWorld 应用开发](./part4/01-HelloWorld.md)
-- [OmniGate 板级仓库](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate)
-- [WLAN、Bluetooth 与 PCM 调试记录](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate/blob/main/docs/wlan-bluetooth-bringup.md)
-- [MIPI DSI 4-Lane 屏调试记录](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate/blob/main/docs/mipi-dsi-debug-record.md)
-- [Bluetooth 音响交付变更说明](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate/blob/main/docs/bluetooth-speaker-change-set.md)
-- [OmniGate AMP Shell 异构开发](./part5/05-OmniGateAMPShell.md)
+1. [获取源码、工具与手册](./02-SourceCodeToolDocumentationManual.md)
+2. [安装并配置开发环境](./03-ConfigHostEnv.md)
+3. [连接并启动开发板](./part1/01-QuickStart.md)
+4. [更新系统固件](./part1/02-FlashSystem.md)
+5. [体验板载功能](./part2/01-Ethernet.md)
+6. [编译第一个 Linux 应用](./part4/01-HelloWorld.md)

docs/T153MX/part1/01-QuickStart.md

@@ -69,4 +69,11 @@ cat /proc/partitions
 
 可以看到 Linux 5.10、`armv7l` 和 eMMC 分区信息，说明开发板已经正常启动。
 
-如果串口完全没有输出，先检查供电、GND、TX/RX 是否接反和串口设备是否选错；如果输出乱码，确认波特率为 115200。
+## 启动成功的判断标准
+
+- 串口日志能够依次看到 Boot0、U-Boot 和 Linux 启动过程。
+- 最终进入 Linux Shell，输入命令能够正常返回。
+- `uname -a` 显示 Linux 5.10，`uname -m` 显示 `armv7l`。
+- `cat /proc/partitions` 能看到板载 eMMC 分区。
+
+串口无输出、乱码或系统停在启动阶段时，转到[启动与烧录常见问题](./03-CommonIssues.md)逐项排查。

docs/T153MX/part1/02-FlashSystem.md

@@ -96,17 +96,11 @@ df -h
 
 能够正常进入 Shell，并看到 Linux 5.10 和 eMMC 分区，说明固件烧录成功。接下来可以进入[板载功能体验](../part2/01-Ethernet.md)。
 
-## 常见问题
+## 烧录成功的判断标准
 
-### 扫描不到设备
+- 烧录工具完整执行并明确提示成功。
+- 重新上电后能从 UART0 看到 Boot0、U-Boot 和 Linux 日志。
+- 能进入 Linux Shell，并看到 Linux 5.10 和 eMMC 分区。
+- 实际启动的镜像与本次选择的方案和构建时间一致。
 
-- 确认使用的是数据线，不是仅充电线。
-- 换一个主机 USB 口。
-- 重新执行板卡的 FEL/FES 进入操作。
-- 保留串口日志，确认开发板当前停在哪个启动阶段。
-
-### 烧录成功但不能启动
-
-- 确认固件属于 `t153_omnigate_mmc-buildroot`。
-- 检查镜像复制前后的 SHA-256 是否一致。
-- 保存从上电开始的完整串口日志，根据 Boot0、U-Boot 或 Kernel 停止位置排查。
+扫描不到设备、烧录后不能启动等问题统一见[启动与烧录常见问题](./03-CommonIssues.md)。

docs/T153MX/part1/03-CommonIssues.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 3
+sidebar_label: 启动与烧录问题
+---
+
+# 启动与烧录常见问题
+
+本页集中处理首次启动和烧录阶段最常遇到的问题。排查时保留从上电开始的完整串口日志，不要只截取最后一行报错。
+
+## 串口没有任何输出
+
+依次确认：
+
+1. 开发板供电正常，电源规格与当前板卡要求一致。
+2. USB 转串口使用 3.3 V TTL 电平，而不是 RS232 电平。
+3. GND 已连接，TXD 与 RXD 已交叉连接。
+4. 选择了实际出现的 `/dev/ttyUSB*` 或 `/dev/ttyACM*`。
+5. 串口参数为 115200、8 数据位、无校验、1 停止位、无流控。
+
+## 串口输出乱码
+
+先关闭当前终端，再用 115200 波特率重新打开。如果仍然乱码，确认连接的是 UART0 调试口，而不是 RS485 或其他复用串口。
+
+## OpenixCLI 扫描不到设备
+
+- 确认连接的是烧录/OTG 接口，并使用支持数据传输的 USB 线。
+- 更换主机 USB 口，避免使用供电不足的扩展坞。
+- 按当前板卡的按键操作重新进入 FEL/FES 模式。
+- 在 Ubuntu 主机执行 `lsusb`，确认 USB 设备是否发生变化。
+
+## 烧录成功但系统不能启动
+
+1. 确认镜像属于 `t153_omnigate_mmc-buildroot` 方案。
+2. 对比镜像复制前后的 SHA-256，排除文件损坏。
+3. 根据串口日志判断停止在 Boot0、U-Boot 还是 Linux 内核阶段。
+4. 如果修改过设备树、分区表或根文件系统，重新使用未修改的基准镜像验证硬件。
+
+## 进入 Shell 后没有预期设备
+
+先确认运行的是本次烧录的固件：
+
+```bash
+uname -a
+cat /proc/cmdline
+cat /proc/partitions
+```
+
+某个接口没有设备节点时，再检查对应驱动、设备树状态和启动日志。板级配置中“已配置”不等于当前镜像已经启用并完成实板验证。
+
+问题仍无法定位时，请同时保存以下信息：固件文件名及 SHA-256、板卡批次、接线照片、完整串口日志和复现步骤。

docs/T153MX/part1/04-StudyPath.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 4
+sidebar_label: Linux 学习路线
+---
+
+# OmniGate-T153 Linux 学习路线
+
+不需要从头读完所有参考手册。先完成能运行、能联网、能编译应用的最小闭环，再按项目需要进入系统定制或 AMP 专题。
+
+```mermaid
+flowchart LR
+    A[认识单板] --> B[串口启动]
+    B --> C[烧录固件]
+    C --> D[板载功能测试]
+    D --> E[HelloWorld 应用]
+    E --> F{开发方向}
+    F --> G[Linux 应用与 Qt]
+    F --> H[Buildroot 与系统配置]
+    F --> I[USB / OTA]
+    F --> J[A7 + E907 AMP]
+```
+
+## 第一步：启动并确认系统
+
+- [启动开发板](./01-QuickStart.md)
+- [更新系统固件](./02-FlashSystem.md)
+- [启动与烧录常见问题](./03-CommonIssues.md)
+
+完成标志：能够从 UART0 进入 Linux Shell，并确认 Linux 5.10、Arm 架构和 eMMC 分区。
+
+## 第二步：完成板载功能测试
+
+依次测试双网口、Wi-Fi/Bluetooth、CAN FD、RS485、USB、TF 卡和按键。每项测试都应保留命令、实际输出和接线记录。
+
+完成标志：项目会使用的接口至少完成一次发送、接收或读写闭环。
+
+## 第三步：开发 Linux 应用
+
+- [HelloWorld 快速入门](../part4/01-HelloWorld.md)
+- [Qt 应用环境部署](../part4/02-QtApplication.md)
+
+完成标志：能在 Ubuntu 主机交叉编译 Arm 程序，上传到开发板并正确运行。
+
+## 第四步：定制系统或学习异构开发
+
+需要裁剪根文件系统、添加软件包时进入 Tina-SDK 开发；需要升级维护时学习 OTA；需要实时控制或多核协作时再进入 OmniGate AMP Shell。
+
+长篇的系统软件、Buildroot、系统配置、USB、OTA 和异构通信文档是按需查询的进阶参考，不要求新手顺序通读。

docs/T153MX/part2/01-Ethernet.md

@@ -69,3 +69,12 @@ ping -I eth0 -c 4 <GATEWAY_IP>
 将 `<GATEWAY_IP>` 替换为 `ip route` 显示的网关地址。出现 4 个回复且没有丢包，表示该网口可用。
 
 拔下网线，连接第二个 RJ45，对另一个接口重复以上步骤。两个接口都能获得地址并 Ping 通，双网口测试完成。
+
+## 测试通过标准
+
+- 两个物理网口都能在 Linux 中找到对应接口。
+- 插拔网线时，对应接口的链路状态会变化。
+- 两个接口都能通过 DHCP 获取 IPv4 地址。
+- 分别指定接口 Ping 网关时能够收到回复。
+
+如果接口存在但始终没有 `LOWER_UP`，优先检查网线、交换机端口和 PHY 链路；如果链路正常但无法获取地址，检查 DHCP 服务和路由配置。

docs/T153MX/part2/02-WiFiBluetooth.md

@@ -92,3 +92,11 @@ scan on
 scan off
 quit
 ```
+
+## 测试通过标准
+
+- `wlan0` 存在，驱动和 firmware 日志没有加载失败。
+- `wpa_cli` 显示 `wpa_state=COMPLETED`，开发板获得 IP 地址并能 Ping 通网关。
+- `hci0` 能够启用，`bluetoothctl` 可以扫描到附近设备。
+
+Wi-Fi 找不到接口时先检查 AIC8800D80 的 SDIO 驱动与 firmware；蓝牙没有 `hci0` 时检查 UART、复位脚和板级初始化服务，不要只重复执行扫描命令。

docs/T153MX/part2/03-CAN.md

@@ -16,7 +16,19 @@ sidebar_label: CAN FD 测试
 
 :::warning 当前基础配置
 
-当前 SDK 的 `linux-5.10-origin/board.dts` 中 `can0`、`can1` 仍为 `disabled`。因此基础镜像不会出现 CAN 网络接口。需要先把两个节点改为 `okay`，重新编译、打包和烧录，再执行本实验。
+当前 SDK 已启用 CAN、CAN Device 和 CAN RAW 内核配置，但以下文件中的 `can0`、`can1` 仍为 `disabled`：
+
+```text
+device/config/chips/t153/configs/omnigate/linux-5.10-origin/board.dts
+```
+
+因此基础镜像不会出现 CAN 网络接口。把两个控制器节点的状态改为：
+
+```dts
+status = "okay";
+```
+
+然后按[SDK 环境与编译](../part3/01-DevelopmentEnvironmentSetup.md)重新编译、打包并按[更新系统固件](../part1/02-FlashSystem.md)烧录，再继续本实验。
 
 :::
 
@@ -36,6 +48,14 @@ GND     -------- GND
 
 在 **开发板 Linux Shell**执行：
 
+```bash
+ip -br link show | grep can
+```
+
+应能看到 `can0` 和 `can1`。如果没有输出，说明控制器尚未启用或当前启动的不是新固件，不要继续执行后面的发送测试。
+
+安装有 `can-utils` 后，继续执行：
+
 ```bash
 ip link set can0 type can bitrate 500000
 ip link set can1 type can bitrate 500000
@@ -74,3 +94,11 @@ cansend can0 123#1122334455667788
 ip link set can0 down
 ip link set can1 down
 ```
+
+## 测试通过标准
+
+- `can0`、`can1` 均能正常置为 UP，状态中没有持续增长的错误计数。
+- CAN0 发送的数据能被 CAN1 原样接收。
+- 交换发送和接收方向后仍能通信。
+
+如果接口进入 `BUS-OFF`，先关闭接口，再检查两端波特率、CAN_H/CAN_L、共地和 120 Ω 终端电阻，确认无误后重新启用。