sipeed · kingo0807 · Jul 10, 2026
diff --git a/docs/doc/assets/maixhub_home.png b/docs/doc/assets/maixhub_home.png
diff --git a/docs/doc/assets/maixhub_train_annotate_page.png b/docs/doc/assets/maixhub_train_annotate_page.png
diff --git a/docs/doc/assets/maixhub_train_device_qrcode.png b/docs/doc/assets/maixhub_train_device_qrcode.png
diff --git a/docs/doc/assets/maixhub_train_manual_deploy_maixvision.png b/docs/doc/assets/maixhub_train_manual_deploy_maixvision.png
diff --git a/docs/doc/assets/maixhub_train_manual_deploy_package.png b/docs/doc/assets/maixhub_train_manual_deploy_package.png
diff --git a/docs/doc/assets/maixhub_train_manual_deploy_page.png b/docs/doc/assets/maixhub_train_manual_deploy_page.png
diff --git a/docs/doc/assets/maixhub_train_manual_deploy_result.png b/docs/doc/assets/maixhub_train_manual_deploy_result.png
diff --git a/docs/doc/assets/maixhub_train_manual_deploy_upload.png b/docs/doc/assets/maixhub_train_manual_deploy_upload.png
diff --git a/docs/doc/assets/maixhub_train_model_type.png b/docs/doc/assets/maixhub_train_model_type.png
diff --git a/docs/doc/assets/maixhub_train_parameters.png b/docs/doc/assets/maixhub_train_parameters.png
diff --git a/docs/doc/assets/maixhub_train_result.png b/docs/doc/assets/maixhub_train_result.png
diff --git a/docs/doc/assets/maixhub_train_split_validation.png b/docs/doc/assets/maixhub_train_split_validation.png
diff --git a/docs/doc/assets/maixhub_train_validation_failed.png b/docs/doc/assets/maixhub_train_validation_failed.png
diff --git a/docs/doc/assets/maixhub_train_video_entries.png b/docs/doc/assets/maixhub_train_video_entries.png
diff --git a/docs/doc/en/README.md b/docs/doc/en/README.md
@@ -7,13 +7,57 @@ title: MaixCAM MaixPy Quick Start
         width: 100%;
         display: table;
     }
+    .device-list {
+      display: flex;
+      flex-direction: column;
+      gap: 0.8em;
+      margin: 1.2em 0;
+    }
+    .device-item {
+      display: grid;
+      grid-template-columns: 13em 1fr auto;
+      gap: 1em;
+      align-items: center;
+      border: 1px solid #e6e8ef;
+      border-radius: 8px;
+      padding: 0.8em;
+      background: #fff;
+    }
+    .device-item img {
+      width: 100%;
+      height: 6.8em;
+      object-fit: contain;
+      background: #f7f8fb;
+      border-radius: 6px;
+    }
+    .device-name {
+      display: block;
+      font-weight: 700;
+      font-size: 1.05em;
+    }
+    .device-desc {
+      margin: 0;
+    }
+    .device-link {
+      white-space: nowrap;
+      font-weight: 600;
+    }
 
     @media screen and (max-width: 900px){
       #head_links th, #head_links td {
           /* padding: 8px; */
           font-size: 0.9em;
           padding: 0.1em 0.05em;
       }
+      .device-item {
+          grid-template-columns: 1fr;
+      }
+      .device-item img {
+          height: 8em;
+      }
+      .device-link {
+          white-space: normal;
+      }
     }
 </style>
 
@@ -42,15 +86,29 @@ title: MaixCAM MaixPy Quick Start
 > For an introduction to MaixPy, please see the [MaixPy official website homepage](../../README.md)
 > Please give the [MaixPy project](https://github.com/sipeed/MaixPy) a Star ⭐️ to encourage us to develop more features if you like MaixPy.
 
-<iframe style="width:100%;min-height:30em" src="https://www.youtube.com/embed/qV1lw0UVUYI?si=g3xUX5v3iT9r7RxJ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+## Choose Your Device First
 
-## Quick Preview
+There are several MaixCAM series products. If this is your first time using one, check the model name on the package, order page, or device enclosure first, then open the corresponding getting-started guide. Choosing the right guide first can save a lot of detours.
 
-<div align="center"><span style="color: #c33d45; font-weight: bold;">MaixCAM2(The Upgraded Version of MaixCAM~)</span></div>
-<iframe src="//player.bilibili.com/player.html?isOutside=true&aid=115547387727388&bvid=BV1veCTBsEZa&cid=33995951833&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>
+<div class="device-list">
+  <div class="device-item">
+    <img src="https://wiki.sipeed.com/static/image/maixcam2_front_back.png" alt="MaixCAM2">
+    <p class="device-desc"><span class="device-name">MaixCAM2</span></p>
+    <a class="device-link" href="./README_MaixCAM2.html">Quick Start MaixCAM2</a>
+  </div>
+  <div class="device-item">
+    <img src="/static/image/maixcams.png" alt="MaixCAM and MaixCAM-Pro">
+    <p class="device-desc"><span class="device-name">MaixCAM / MaixCAM-Pro</span></p>
+    <a class="device-link" href="./README_MaixCAM.html">Quick Start MaixCAM</a>
+  </div>
+  <div class="device-item">
+    <img src="/static/image/maixcam.png" alt="MaixCAM Lite">
+    <p class="device-desc"><span class="device-name">MaixCAM Lite / screenless version</span></p>
+    <a class="device-link" href="./README_no_screen.html">Quick Start MaixCAM screenless version</a>
+  </div>
+</div>
 
-<div align="center"><span style="color: #c33d45; font-weight: bold;">MaixCAM</span></div>
-<iframe src="//player.bilibili.com/player.html?isOutside=true&aid=113485669204279&bvid=BV1ncmRYmEDv&cid=26768769718&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" class="biliiframe"></iframe>
+<iframe style="width:100%;min-height:30em" src="https://www.youtube.com/embed/qV1lw0UVUYI?si=g3xUX5v3iT9r7RxJ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 ## Before Start
 
@@ -82,17 +140,6 @@ Purchase Links:[Sipeed Taobao](https://item.taobao.com/item.htm?id=846226367137)
 
 >! Note that currently only the MaixCAM development board is supported. Other development boards with the same chip are not supported, including Sipeed's development boards with the same chip. Please be careful not to purchase the wrong board, which could result in unnecessary waste of time and money.
 
-
-## Getting Started
-
-Please select the documentation corresponding to your hardware platform to proceed:
-
-| Hardware Platform | Getting Started Guide |
-|-|-|
-|MaixCAM Lite|[Quick Start MaixCAM(Screenless Version)](./README_no_screen.md)|
-|MaixCAM/MaixCAM Pro|[Quick Start MaixCAM](./README_MaixCAM.md)|
-|MaixCAM2|[Quick Start MaixCAM2](./README_MaixCAM2.md)|
-
  ## Next Steps
 
  If you like what you've seen so far, **please be sure to give the MaixPy open-source project a star on [GitHub](https://github.com/sipeed/MaixPy) (you need to log in to GitHub first). Your star and recognition is the motivation for us to continue maintaining and adding new features!**

diff --git a/docs/doc/en/README_MaixCAM.md b/docs/doc/en/README_MaixCAM.md
@@ -7,6 +7,12 @@ title: MaixCAM MaixPy Quick Start
         width: 100%;
         display: table;
     }
+    .biliiframe {
+      width: 100%;
+      min-height: 30em;
+      border-radius: 0.5em;
+      border: 1em solid white;
+    }
 
     @media screen and (max-width: 900px){
       #head_links th, #head_links td {
@@ -19,6 +25,10 @@ title: MaixCAM MaixPy Quick Start
 
 ## Getting Started
 
+### Getting Started Video
+
+<iframe src="//player.bilibili.com/player.html?isOutside=true&aid=113485669204279&bvid=BV1ncmRYmEDv&cid=26768769718&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" class="biliiframe"></iframe>
+
 ### Prepare the TF Image Card and Insert it into the Device
 
 If the package you purchased includes a TF card, it already contains the factory image. If the TF card was not installed in the device at the factory, you will first need to carefully open the case (be careful not to tear the ribbon cables inside) and then insert the TF card. Additionally, since the firmware from the factory may be outdated, it is highly recommended to follow the instructions on [Upgrading and Flashing the System](./basic/os.md) to upgrade the system to the latest version.
@@ -158,4 +168,4 @@ Here is the translation:
 
  If you want the program to start automatically on boot, you can set it in `Settings -> Boot Startup`.
 
- More MaixVision usage refer to [MaixVision documentation](./basic/maixvision.md)。
+ More MaixVision usage refer to [MaixVision documentation](./basic/maixvision.md)。
diff --git a/docs/doc/en/README_MaixCAM2.md b/docs/doc/en/README_MaixCAM2.md
@@ -7,6 +7,12 @@ title: MaixCAM2 MaixPy Quick Start
         width: 100%;
         display: table;
     }
+    .biliiframe {
+      width: 100%;
+      min-height: 30em;
+      border-radius: 0.5em;
+      border: 1em solid white;
+    }
 
     @media screen and (max-width: 900px){
       #head_links th, #head_links td {
@@ -19,7 +25,11 @@ title: MaixCAM2 MaixPy Quick Start
 
 ## Getting Started
 
->! MaixCAM2 has built-in eMMC storage, so it can operate without requiring a TF card. If you need to upgrade or flash the system, please refer directly to the <a href="./basic/os" target="_blank">System Upgrade and Flashing</a> guide.
+>! MaixCAM2 is available in versions with and without eMMC storage. The 32GB eMMC version normally boots from eMMC and does not require a TF card for daily use; the version without eMMC must use a TF card with a flashed system to boot. A TF card can also be used to boot from TF card, or to flash or recover the system to eMMC. For system upgrade or flashing, see <a href="./basic/os" target="_blank">System Upgrade and Flashing</a>.
+
+### Getting Started Video
+
+<iframe src="//player.bilibili.com/player.html?isOutside=true&aid=115547387727388&bvid=BV1veCTBsEZa&cid=33995951833&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" class="biliiframe"></iframe>
 
 ### Power On
 
@@ -154,4 +164,4 @@ Here is the translation:
 
  If you want the program to start automatically on boot, you can set it in `Settings -> Boot Startup`.
 
- More MaixVision usage refer to [MaixVision documentation](./basic/maixvision.md)。
+ More MaixVision usage refer to [MaixVision documentation](./basic/maixvision.md)。
diff --git a/docs/doc/en/ai_model_converter/ai_model_deploy.md b/docs/doc/en/ai_model_converter/ai_model_deploy.md
@@ -0,0 +1,15 @@
+---
+title: AI Model Download, Debugging, and Deployment Guide
+---
+
+## Choose a Model Deployment Workflow
+
+Before deploying a local model on MaixCAM2, first identify the model source and deployment path. Choose the workflow that matches your current resources instead of starting with ONNX conversion immediately.
+
+| Goal | Recommended workflow | Documentation |
+| --- | --- | --- |
+| Use built-in or ready-made models | Use built-in models first. For more resolutions or class sets, filter MaixCAM2 models in [MaixHub Model Zoo](https://maixhub.com/model/zoo?platform=maixcam2). Model packages usually include a `.mud` file and corresponding `.axmodel` files, which should be placed in the same directory on the device | [Model and dataset sources](../pro/datasets.md) |
+| Train a custom recognition target | Use MaixHub online training to complete data collection, annotation, training, and deployment | [MaixHub online training](../vision/maixhub_train.md) |
+| Deploy an ONNX model | Follow the MaixCAM2 conversion workflow to convert ONNX into `.mud` + `.axmodel` files before deployment | [MaixCAM2 model conversion](./maixcam2.md) |
+
+After choosing your workflow, continue with the corresponding document.
diff --git a/docs/doc/en/ai_model_converter/maixcam2.md b/docs/doc/en/ai_model_converter/maixcam2.md
@@ -10,6 +10,8 @@ Models trained on a computer cannot be directly used on MaixCAM2 due to its limi
 
 This article describes how to convert an ONNX model into a model usable by MaixCAM2 (MUD model).
 
+If you are not sure whether to download an existing model, train online, or convert ONNX yourself, read the [beginner model download, debugging, and deployment guide](./ai_model_deploy.md) first.
+
 ## Supported Model File Format for MaixCAM2
 
 MUD (Model Universal Description) is a model description file supported by MaixPy that unifies models across different platforms, making MaixPy code cross-platform. It is a text file in `ini` format and can be edited with a text editor.
@@ -178,10 +180,50 @@ Edit as per your model. For YOLO11:
 
 The `[basic]` section is required. Once set, you can load and run the model using `maix.nn.NN` in `MaixPy` or `MaixCDK`.
 
+## Deploy to the Device and Verify Quickly
+
+MaixPy usually loads the `.mud` file. The `.mud` file then points to the actual `.axmodel` files. The simplest approach is to put them in the same directory, for example:
+
+```text
+/root/models/my_model.mud
+/root/models/my_model_npu.axmodel
+/root/models/my_model_vnpu.axmodel
+```
+
+Then first confirm that the model can be loaded:
+
+```python
+from maix import nn
+
+model = nn.NN("/root/models/my_model.mud")
+print(model)
+```
+
+If the model type is already supported by MaixPy, prefer the wrapped API. For example, for YOLO, see the [YOLO object detection documentation](../vision/yolov5.md):
+
+```python
+from maix import nn
+
+detector = nn.YOLO11(model="/root/models/yolo11n.mud", dual_buff=True)
+```
+
+## Debug Checklist
+
+If the model cannot be loaded or the result is wrong, check these items first:
+
+1. Whether the `.mud` and `.axmodel` files are in the same directory, and whether `model_npu` and `model_vnpu` in the `.mud` file use the correct file names.
+2. Whether the path used on the device really exists, such as `/root/models/xxx.mud`.
+3. Whether `labels` exactly matches the class count and class order used during training.
+4. Whether `model_type` is supported by MaixPy, such as `yolo11`, `yolov8`, or `classifier`.
+5. Whether input resolution, `mean`, `scale`, and RGB/BGR order match training, export, and conversion settings.
+6. Whether the ONNX output nodes exactly match `output_processors` in `config.json`.
+7. If you are not sure whether the problem is the model or your code, test with a MaixHub model or a built-in model first. After an official model runs correctly, debug your own model.
+
+After these basic checks pass, continue with the specific model documentation or conversion workflow.
+
 If MaixPy doesn't support your model, define your own `extra` fields and write decoding logic. You can either:
 
 * Use Python in `MaixPy` to load the model via `maix.nn.NN`, run `forward`/`forward_image`, and process the outputs in Python (easier but slower);
 * Or, for better performance and reusable integration, write C++ logic in `MaixCDK`, see [YOLOv5 example](https://github.com/sipeed/MaixCDK/blob/71d5b3980788e6b35514434bd84cd6eeee80d085/components/nn/include/maix_nn_yolov5.hpp).
 
 Once done, consider submitting a PR to `MaixPy` or share your model on [MaixHub](https://maixhub.com/share) to earn rewards ranging from ¥30 to ¥2000!
-
diff --git a/docs/doc/en/basic/upgrade.md b/docs/doc/en/basic/upgrade.md
@@ -8,20 +8,24 @@ First, let's distinguish between **`System`** and **`MaixPy`**:
 * **System**: The foundation for running all software, including the operating system and drivers, serving as the cornerstone for software operation.
 * **MaixPy**: A software package that relies on system drivers to function.
 
-## Getting the Latest System
+## Get the Latest System and Flash It to Hardware
 
-Find the latest system image files on the [MaixPy Releases page](https://github.com/sipeed/MaixPy/releases), for example:
+Before flashing, confirm both the device model and where the system is stored. MaixCAM / MaixCAM-Pro run the system from a TF card, so a TF card is required. MaixCAM2 normally runs from onboard eMMC, so a TF card is usually not required for regular updates. For regular updates, use the USB flashing workflow in the corresponding flashing page first; when booting from a TF card, recovering the system, or replacing storage media, follow the method described on that page.
 
-* `maixcam_os_20240401_maixpy_v4.1.0.xz`: MaixCAM system image including MaixPy v4.1.0.
-* `maixcam-pro_os_20240401_maixpy_v4.1.0.xz`: MaixCAM Pro system image including MaixPy v4.1.0.
-* `maixcam2_os_20250801_maixpy_v4.11.0.xz`: MaixCAM2 system image including MaixPy v4.11.0. Since the MaixCAM system image exceeds 2GB, it will only be available on Sourceforge. Users in China can download it via the shared files in the QQ group.
+After confirmation, use the table below to choose the correct system image and flashing page.
 
-<span style="color: #e91e63; font-weight: 800">**Make sure to download the system image that corresponds to your device model**</span>. Downloading the wrong image may cause device damage.
+| Device | Download entry | File to choose | Flashing page |
+| --- | --- | --- | --- |
+| MaixCAM | [MaixPy Releases page](https://github.com/sipeed/MaixPy/releases) | `maixcam-*.img.xz` | [MaixCAM System Flashing](https://wiki.sipeed.com/hardware/zh/maixcam/os.html) |
+| MaixCAM-Pro | [MaixPy Releases page](https://github.com/sipeed/MaixPy/releases) | `maixcam-pro-*.img.xz` | [MaixCAM System Flashing](https://wiki.sipeed.com/hardware/zh/maixcam/os.html) |
+| MaixCAM2 | [Baidu Netdisk (extraction code: vjex)](https://pan.baidu.com/s/1r4ECNlaTVxhWIafNBZOztg) | `maixcam2-*-maixpy-*_sd.img.7z.*` | [MaixCAM2 System Flashing](https://wiki.sipeed.com/hardware/zh/maixcam/maixcam2_os.html) |
 
-> Users in China with slow download speeds can use tools like Xunlei for faster downloads.
-> Alternatively, use proxy sites such as [github.abskoop.workers.dev](https://github.abskoop.workers.dev/) for downloads.
+<span style="color: #e91e63; font-weight: 800">**Make sure to download the system image that corresponds to your device model**</span>. Downloading the wrong image may cause abnormal behavior and may require recovery flashing.
+
+When downloading, choose the newest file that matches the "File to choose" column in the table. For MaixCAM and MaixCAM-Pro, select the corresponding image on the releases page. MaixCAM2 images are split 7z archives; download all `.7z.00x` parts of the same version from Baidu Netdisk before extracting and flashing.
 
-Backup mirror: [Sourceforge](https://sourceforge.net/projects/maixpy/files/) (may not be up-to-date, so prefer the above official sources)
+
+> Users in China with slow download speeds can use tools like Xunlei for faster downloads.
 
 
 ## Backup Your Data
@@ -37,18 +41,6 @@ Backup methods:
 * Remove the storage media and use a card reader to copy files directly. Note: the root filesystem is formatted as `ext4`, which Windows does not support by default (you can use third-party software like DiskGenius to read it).
 
 
-## Flashing the System to Hardware
-
-| Item          | MaixCAM / MaixCAM-Pro    | MaixCAM2      |
-| --------------- | ---------- | ------ |
-| Flashing Docs      | [MaixCAM System Flashing](https://wiki.sipeed.com/hardware/zh/maixcam/os.html) | [MaixCAM2 System Flashing](https://wiki.sipeed.com/hardware/zh/maixcam/maixcam2_os.html) |
-| System Storage     | TF Card    | Built-in EMMC (/TF Card)    |
-| TF Card Required   | Yes   | No   |
-| Flashing Method    | USB flashing or card reader flashing   | USB flashing or card reader flashing |
-| Recommended Method | USB flashing   | USB flashing   |
-| Recovery Flashing  | Card reader flashing     | USB flashing / card reader flashing    |
-
-
 ## When to Update the System vs. Updating MaixPy Only
 
 To simplify the process and avoid issues, it is **recommended to update the system whenever upgrading MaixPy**.

diff --git a/docs/doc/en/pro/datasets.md b/docs/doc/en/pro/datasets.md
@@ -8,6 +8,14 @@ title: MaixCAM MaixP Where to Find Models and Datasets
 
 Visit the [MaixHub Model Library](https://maixhub.com/model/zoo) and filter by the corresponding hardware platform to find suitable models.
 
+If you only want to verify that the workflow works, start with a built-in model. The system usually includes common models in `/root/models`, so you can reference the corresponding `.mud` file directly in your code without downloading anything.
+
+For more models, open [MaixHub Model Zoo](https://maixhub.com/model/zoo?platform=maixcam2), filter by the MaixCAM2 platform, and download a model package. After downloading, check whether it contains:
+
+- `.mud`: the model description file. MaixPy code usually loads this file.
+- `.axmodel`: the actual model file that runs on MaixCAM2.
+- Example code or instructions: if the model page provides an example, run that first.
+
 ## What Are Datasets Used For?
 
 First, check the [MaixHub Model Library](https://maixhub.com/model/zoo) to see if there’s a model you need. If not, you can train your own model. Training a model requires a dataset, which provides the data needed for training.

diff --git a/docs/doc/en/sidebar.yaml b/docs/doc/en/sidebar.yaml
@@ -137,24 +137,26 @@ items:
         label: Whisper Speech-Recognition Model
     -   file: mllm/tts_melotts.md
         label: MeloTTS Speech-Synthesis Model
--   label: Local NPU deployment of AI models
+-   label: Local deployment of AI models
     items:
+    -   file: ai_model_converter/ai_model_deploy.md
+        label: AI model download and deployment guide
+    -   file: pro/datasets.md
+        label: Where to find models & datasets
+    -   file: vision/maixhub_train.md
+        label: MaixHub online AI training
+    -   file: vision/customize_model_yolo.md
+        label: YOLO model offline training
     -   file: ai_model_converter/maixcam2.md
-        label: ONNX model to MaixCAM2's
+        label: Convert ONNX model for MaixCAM2
     -   file: ai_model_converter/maixcam.md
-        label: ONNX model to MaixCAM's
+        label: Convert ONNX model for MaixCAM
     -   file: ai_model_converter/onnx_export.md
         label: Trim ONNX model output nodes
     -   file: ai_model_converter/web_converter.md
         label: Convert YOLO models with Web UI
-    -   file: pro/datasets.md
-        label: Where to find models & datasets
     -   file: pro/customize_model.md
-        label: Customize new AI model
-    -   file: vision/maixhub_train.md
-        label: MaixHub online AI training
-    -   file: vision/customize_model_yolo.md
-        label: YOLO model offline training
+        label: Port a new AI model