Administrator/NANOKVM-sipeed_wiki-MIRROR
1
0
Fork 0
mirror of https://github.com/sipeed/sipeed_wiki.git synced 2026-09-11 00:22:49 -05:00
Code Issues Packages Projects Releases Wiki Activity

Add EN translated documentation for Maix-IV series including M4N-Dock and M4N-Hat

Browse Source
This commit is contained in:
taorye
2025-07-10 15:13:38 +08:00
parent baab64e506
commit 150e3935c3
12 changed files with 1036 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/hardware/en/maixIV/.gitkeep
View File

3
docs/hardware/en/maixIV/README.md
View File

@@ -1,3 +0,0 @@
Coming soon

65
docs/hardware/en/maixIV/m4n/FAQ.md Normal file
View File

@@ -0,0 +1,65 @@
## How to enable root user password login for SSH when the correct password is entered but login fails?
Default password: root
*For security reasons, the default policy only allows the root user to log in remotely via SSH key authentication, which is not only convenient and fast but also secure. The required steps are as follows: After logging into the system via serial port or desktop, manually paste your public key into the `/root/.ssh/authorized_keys` file (create the file if it does not exist). For a more detailed process, you can search for "SSH login with key" or refer directly to this [tutorial](https://www.runoob.com/w3cnote/set-ssh-login-key.html)。*
If you insist on enabling password login, follow these steps:
```bash
# Log in via the serial terminal and execute the following commands:
# Enable remote password login for the root user
echo "PermitRootLogin yes" > /etc/ssh/sshd_config.d/allow-root.conf
systemctl restart sshd
```
After development, to avoid risks caused by accidental root password leakage, it is recommended to disable remote password login for the root user by executing the following commands:
```bash
# Log in to any terminal and execute the following commands:
# Disable remote password login for the root user
rm /etc/ssh/sshd_config.d/allow-root.conf
systemctl restart sshd
```
## Q: The root filesystem partition is too small by default when using TFCard & eMMC images. How to expand eMMC or TFCard?
```bash
# Log in to any terminal and execute the following commands:
# Replace mmcblkX below with mmcblk0 (eMMC) or mmcblk1 (TFCard).
# /dev/mmcblkXp2 is the second partition, which is the root filesystem partition.
parted /dev/mmcblkX resizepart 2 100%
resize2fs /dev/mmcblkXp2
sync
```
## Q: Some large language models require executing tokenizer-related Python scripts, but an error "ModuleNotFoundError" occurs. How to resolve this?
```bash
# To avoid polluting the system Python libraries, create a virtual environment:
apt install python3-venv
python3 -m venv venv-llm
# Activate the virtual environment:
source venv-llm/bin/activate
# Install the missing Python modules (use Tsinghua Mirror for faster installation in China):
pip install transformers jinja2 -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
# After installation, you can proceed to execute the script.
```
Remember to activate the virtual environment before running related Python scripts each time:
```bash
# Activate the virtual environment:
source venv-llm/bin/activate
```
## Q: If GPIO2_A27 is configured as I2C3_SCL in the device tree, how can I control GPIO2_A27 when I2C3 is not in use? (pinctrl)
```bash
cd /sys/kernel/debug/pinctrl/4250200.pinctrl
grep "GPIO2_A27" pinmux-functions
# output # function 447: GPIO2_A27, groups = [ I2C3_SCL ]
grep "I2C3_SCL" pinmux-pins
# output # pin 87 (I2C3_SCL): device 2024000.i2c function i2c3_scl group I2C3_SCL
echo 2024000.i2c > /sys/bus/platform/drivers/i2c_designware/unbind
grep "I2C3_SCL" pinmux-pins
# output # pin 87 (I2C3_SCL): UNCLAIMED
# echo "<group-name function-name>" > pinmux-select
echo "I2C3_SCL GPIO2_A27" > pinmux-select
gpioset gpiochip2 27=0
gpioset gpiochip2 27=1
```

34
docs/hardware/en/maixIV/m4n/axmodel-deploy.md Normal file
View File

@@ -0,0 +1,34 @@
# Deploying AI Models on M4N
## Deploying Large Language and Multimodal Models
Obtain models and runtime environments from the following sources. Deployment instructions can be found in each repository's README.md.
Official AXERA Models: https://huggingface.co/AXERA-TECH
China Mirror Site: https://hf-mirror.com/AXERA-TECH
| Model | Link | China Mirror Link |
| -- | -- | -- |
| Qwen3:0.6b | [Qwen3-0.6B-Int8](https://huggingface.co/AXERA-TECH/Qwen3-0.6B) | [Qwen3-0.6B-Int8](https://hf-mirror.com/AXERA-TECH/Qwen3-0.6B) |
| DeepSeek-R1:1.5b | [DeepSeek-R1-Distill-Qwen-1.5B](https://huggingface.co/AXERA-TECH/DeepSeek-R1-Distill-Qwen-1.5B) | [DeepSeek-R1-Distill-Qwen-1.5B](https://hf-mirror.com/AXERA-TECH/DeepSeek-R1-Distill-Qwen-1.5B) |
| Qwen2.5:1.5b | [Qwen2.5-1.5B-Instruct-GPTQ-Int8](https://huggingface.co/AXERA-TECH/Qwen2.5-1.5B-Instruct-GPTQ-Int8) | [Qwen2.5-1.5B-Instruct-GPTQ-Int8](https://hf-mirror.com/AXERA-TECH/Qwen2.5-1.5B-Instruct-GPTQ-Int8) |
| SD1.5 | [lcm-lora-sdv1-5](https://huggingface.co/AXERA-TECH/lcm-lora-sdv1-5) | [lcm-lora-sdv1-5](https://hf-mirror.com/AXERA-TECH/lcm-lora-sdv1-5) |
| InternVL2.5:1b | [InternVL2_5-1B-Int8](https://huggingface.co/AXERA-TECH/InternVL2_5-1B) | [InternVL2_5-1B-Int8](https://hf-mirror.com/AXERA-TECH/InternVL2_5-1B) |
**Important Note:** All above models require system images compiled with `SDK 1.45.0` or `later` to run large models. Please update your system accordingly. Our provided TFCard&eMMC images meet this requirement and reserve 6GB memory for model loading, capable of running 7B parameter int4 models.
*Quick test with Qwen3-0.6b:*
```bash
# Can replace with links to other model repositories
git clone https://hf-mirror.com/AXERA-TECH/Qwen3-0.6B
cd Qwen3-0.6B
# If ModuleNotFoundError occurs, refer to FAQ for details
python3 qwen3_tokenizer_uid.py
# Switch to corresponding execution script and restore necessary permissions
chmod +x main_ax650
sh run_qwen3_0.6b_int8_ctx_ax650.sh
```

122
docs/hardware/en/maixIV/m4n/system-update.md Normal file
View File

@@ -0,0 +1,122 @@
This guide provides detailed instructions for two system flashing methods for the M4N-Dock development board:
1. booting and flashing eMMC via TFCard
2. flashing using the AXDL tool
Please choose the appropriate method based on your needs.
## Image File
*Due to the large size of the image packages used in the flashing methods described on this page and limited bandwidth on the download site, they are stored exclusively on Baidu Enterprise Drive in the same directory. The entry link can be found in the [top side of the download site](https://dl.sipeed.com/)。*
| Image Type | How to Boot | Filename | How to Obtain |
|-------------------|-------------------------------------------|--------------|-------------------|
| TFCard&eMMC Image | `power-up Boot from eMMC` or `Manual boot from TFCard` | `sdcard.img` | path: MaixIV/M4N-Dock/09_Image/TFCard&eMMC Images |
| AXSDK AXP | `power-up Boot from eMMC` | `xxx.axp` | path: MaixIV/M4N-Dock/09_Image/ubuntu |
f the downloaded image file has an .xz extension, decompress it first. Linux users can use the xz tool, while Windows users can use tools like 7-zip.
![](../../../zh/maixIV/assets/baidupan-dl.png)
## Booting and Flashing eMMC via TFCard
### Booting into the Live System (Manual Intervention Required)
#### Step 1: Prepare TFCard and Flash the Image
Prepare a TFCard with at least 8GB capacity and use any card reader tool or the computer's built-in card slot for reading/writing.
Note: The following operations will erase all data on the TFCard. Back up important data beforehand.
| HOST OS | Flashing Method |
|------------|--------------------------------------------------------------------------|
| Linux | `sudo dd if=sdcard.img of=/dev/sdX bs=4M conv=fsync status=progress` |
| Windows | Use `Win32DiskImager`, `Rufus` or `balenaEtcher` to flash the image |
Example for Linux:
```bash
# Assuming the TFCard is mounted as /dev/sdb
% sudo dd if=sdcard.img of=/dev/sdb bs=4G conv=sparse,fsync status=progress
0+3 records in
0+3 records out
5754429440 bytes (5.8 GB, 5.4 GiB) copied, 89.2665 s, 64.5 MB/s
```
#### Step 2: Booting into the Live System Using the Flashed TFCard
**TFCard Boot Method**
| Board | Device Tree Blob | TF Card Slot Location | `BOOT` Button Location |
|------------|-----------------------|--------------------------------|---------------------------|
| Dock | `dtbs/m4nbox.dtb` | Top-left corner, diagonal to Type-C port | Next to Type-C port (labeled BOOT) |
| Hat | `dtbs/m4nhat.dtb` | Behind USB3 port, near the notch | Next to HDMI port (labeled BOOT0) |
| Cluster | `dtbs/m4ncluster.dtb` | Below M.2 slot | Next to Type-C port (labeled BOOT) |
1. Mount the TFCard and modify the `dtb_img_name=dtbs/m4nbox.dtb` line in the FAT32 partition's `config.txt` file to match your board.
2. Insert the TFCard into the TF card slot.
3. Hold the `BOOT` button and reset the board:
- Option 1: Power cycle (unplug and replug power).
- Option 2: Press and release the `RST` button while powered on.
Note for M4N-Dock: If the front panel is obstructed, remove it by unscrewing the 3 screws and rotating it open.
After completing these steps, the Live system should boot. You can observe the boot logs via UART0.
**This Live system is fully functional and ready for immediate use. If you want the system to boot automatically without manual button operations, proceed to flash the image to eMMC as described below.**
### Flashing eMMC from the Live System (Automatic Boot on Power-Up)
The onboard eMMC is always recognized as `/dev/mmcblk0`, while the TFCard is `/dev/mmcblk1`. Be careful to distinguish between them.
There are two methods are provided below for flashing the image to eMMC:
#### Method 1: Directly Recovery from the Live System
1. Boot into the Live system as described earlier and open a terminal for the following steps.
2. Use `dd` to **recovery** the Live system from the TFCard to eMMC:
```sh
dd if=/dev/mmcblk1 of=/dev/mmcblk0 bs=3M count=1 conv=fsync
sync # 确保分区表生效
dd if=/dev/mmcblk1p1 of=/dev/mmcblk0p1 bs=64M conv=fsync
dd if=/dev/mmcblk1p2 of=/dev/mmcblk0p2 bs=1G conv=sparse,fsync status=progress
```
3. After completion, remove the TFCard. Just press the `RST` button and the system will now directly boot from eMMC.
#### Method 2: Flash the Image within the Live System
Prerequisite: The second partition (ext4) of the TFCard must be accessible and writable. If unsure, use Method 1.
1. Copy the sdcard.img file to any location in the second partition (Live system root directory).
2. Flash the image to eMMC:
```sh
dd if=/path/to/sdcard.img of=/dev/mmcblk0 bs=1G conv=sparse,fsync status=progress
```
3. After completion, remove the TFCard. Just press the `RST` button and the system will now directly boot from eMMC.
## Flashing via AXDL Software
The flashing file format has changed to be like `xxx.axp`.
For detailed steps, refer to the `AXDL 工具使用指南.pdf` in the official SDK documentation package.
**Tip: The Download button on the official EVB corresponds to the BOOT button on other boards.**
The AXDL software (Windows only) is located in the `PC_Software` directory on the download site.
**Important Notes for M4N-Dock:**
- **The USB flashing port is the bottom `USB-A port` near the `HDMI` connector (Ethernet side). Use an `A-to-A` cable or `A-to-C` cable if your PC has a `Type-C port`.**
- **Do `not` connect the `12V power supply` during flashing. Use only the USB cable to avoid damaging the `PC's USB port`.**

76
docs/hardware/en/maixIV/m4ndock/FAQ.md Normal file
View File

@@ -0,0 +1,76 @@
---
title: Maix-IV Series Frequently Asked Questions (FAQ)
---
## Q: How to check the SDK version of the current system?
A: Run the command `cat /proc/ax_proc/version`. Example output:
```bash
root@ax650:~# cat /proc/ax_proc/version
Ax_Version V1.45.0_P39_20240830020829
```
## Q: After updating to v1.45.0_P39, the root filesystem is smaller than 5GB. How to expand it?
A: Before expansion:
```bash
root@ax650:~# df -h
Filesystem Size Used Avail Use% Mounted on
/dev/root 4.9G 4.3G 336M 93% /
```
After expansion:
```bash
root@ax650:~# df -h
Filesystem Size Used Avail Use% Mounted on
/dev/root 15G 4.3G 9.6G 31% /
```
Steps:
1. Identify whether the system boots from TFCard or eMMC:
```bash
root@ax650:~# grep -oP 'root=\K\S+' /proc/cmdline
/dev/mmcblk1p2 # TFCard 启动
# /dev/mmcblk0p2 # 或 eMMC 启动
```
2. Replace `/dev/mmcblkX` in the following commands with the detected device (e.g., `/dev/mmcblk0` or `/dev/mmcblk1`), then execute:
```bash
parted /dev/mmcblkX resizepart 2 100%
resize2fs /dev/mmcblkXp2
sync
```
Q: After updating to v1.45, the root filesystem only shows 8GB. How to fix this?
A: This occurs when booting after the first flash. The eMMC partition is pre-configured for maximum capacity. Run the following to update filesystem metadata (post-expansion size should be 28GB):
```bash
resize2fs /dev/mmcblk0p10
sync # Critical! Prevents boot failure after power cycle.
```
Expected result:
```bash
root@maixbox:~# df -h
Filesystem Size Used Avail Use% Mounted on
/dev/root 28G 6.0G 21G 23% /
```
Warning: Always run `sync` before rebooting/power-off to avoid system corruption.
## Q: How to resolve network conflicts caused by duplicate MAC addresses?
A: Permanently modify MAC addresses via U-Boot environment variables:
```bash
# 例如
setenv ethaddr d0:00:00:00:00:01
setenv eth1addr d0:00:00:00:00:02
saveenv
```
## Key Notes:
- For eMMC operations, ensure sync is executed to prevent data loss.
- MAC address changes require saveenv to persist across reboots.
- Refer to official docs for advanced partitioning scenarios.

60
docs/hardware/en/maixIV/m4ndock/intro.md Normal file
View File

@@ -0,0 +1,60 @@
## Introduction
**Taobao link: [Click to Buy](https://item.taobao.com/item.htm?spm=1619a.1.0.0.3f0865abb4Wq5c&id=744014549573&ns=1&abbucket=18#detail)**
The M4N-Dock is an edge computing box featuring hybrid-precision computing capabilities, developed by Sipeed and powered by AXERA's third-generation high-efficiency AI vision chip, the AX650N. It delivers an impressive 72 TOPS@INT4 or 18 TOPS@INT8 of built-in AI computing power, capable of running popular large-scale AI models.
Equipped with an advanced ISP supporting 8K@30fps video processing and AXERA's proprietary AI-ISP technology for superior low-light night vision performance, it also integrates H.264/H.265 codecs capable of stable 8K@60fps decoding and 8K@30fps encoding. Real-world testing demonstrates reliable 32-channel 1080P@30fps decoding and 16-channel 1080P@30fps encoding.
The AX650N chip features comprehensive interfaces including 64-bit LPDDR4x memory, multi-channel MIPI input, Gigabit Ethernet, USB 3.0, and HDMI 2.0b output. Combining powerful computing with exceptional codec capabilities, it meets industry demands for high-performance edge AI computing.
The single-core NPU delivers outstanding performance (single-core performance), achieving:
- 130 FPS (7.66ms latency) for yolov5s at 640×640 resolution
- 1798 FPS (0.556ms latency) for MobileNetV2 at 224×224 resolution
Supporting diverse deep learning algorithms, it enables applications including visual structuring, behavior analysis, and status detection, with optimized support for Transformer architectures and large vision models. Comprehensive development documentation facilitates secondary development for customized solutions.
## Key Specifications
| Component | Description |
|-----------|--------------------------------------------------------------------------------------|
| CPU | 8x A55@1.7Ghz, integrated FPU, supports NEON acceleration |
| NPU | 72 TOPS@INT4 / 18 TOPS@INT8, supporting INT4/INT8/INT16/FP16/FP32 inputs, TopN (N<=32) |
| ISP | Supports up to 8192x4320@30fps, maximum resolution: 16384x16384, featuring AI-ISP (low-light night vision) |
| CODEC | H.264/H.265 encoding/decoding, up to 8K@60fps decoding & 8K@30fps encoding capability |
| DSP | Dual-core 800MHz |
| Memory | 8GB 64-bit LPDDR4x (adjustable allocation: default 2GB system + 6GB AI CMM) |
| Storage | 32GB eMMC 5.1 onboard (system storage) plus 3x SATA 3.0 6Gb/s (1× M.2 + 2× standard SATA ports) |
| Video Output | Dual HDMI 2.0a (4K@60fps max) |
| Video Input | Dual 4-lane MIPI-CSI camera interfaces (3.5Gbps) |
| Network | Dual Gigabit Ethernet ports (tested throughput: 944Mbps) |
| PCIE | 1-lane PCIe 2.0 (5Gbps) via Mini-PCIe interface |
| USB | 1× USB3.2 Gen1 (5Gbps) + 3× USB2.0 (480Mbps) (blue port farthest from Ethernet is OTG programming port) |
| Others | 1x RS485 + 1x RS232 + 3x user controlled led |
## Resources
### Hardware Documentation
Datasheet: https://dl.sipeed.com/shareURL/MaixIV/M4N-Dock
### Software Documentation
Docs: https://dl.sipeed.com/shareURL/MaixIV/M4N-Dock
SDK: https://github.com/AXERA-TECH/ax650n_bsp_sdk
### AI Development
AI Toolchain (ONNX Conversion/Deployment)
- Pulsar2 (AXERA's ALL-IN-ONE Neural Network Compiler):
Docs: https://pulsar2-docs.readthedocs.io/en/latest/pulsar2/introduction.html
Download: https://pan.baidu.com/s/1FazlPdW79wQWVY-Qn--qVQ?pwd=sbru
op_support_list: https://pulsar2-docs.readthedocs.io/en/latest/appendix/op_support_list_ax650.html
Samples source: https://github.com/AXERA-TECH/ax-samples
## Technical Support
For custom development (kernel/OS customization, application-layer SDKs), contact: support@sipeed.

211
docs/hardware/en/maixIV/m4ndock/quick-start.md Normal file
View File

@@ -0,0 +1,211 @@
## System Boot and Login
**Note:** The system must be powered via 12V DC input. USB power alone may cause insufficient power supply leading to system instability.
### Pre-Boot Preparation
Required:
1. 12V DC power supply
2. HDMI cable and display
3. Type-C cable (optional: for serial debugging/login)
4. RJ45 Ethernet cable (optional: for network connection and SSH login)
For first-time use, verify the following status matches your hardware version:
- Power switch on enclosure is ON (for enclosed versions)
- Jumper cap remains shorted at Button marking (for bare board versions)
![top](../../../zh/maixIV/assets/top.png)
### Normal Boot
Connect display via HDMI1 and provide 12V DC power. After approximately 20 seconds, the LightDM login interface will appear, indicating successful system boot.
![desktop](../../../zh/maixIV/assets/desktop.jpg)
Connect mouse/keyboard to the onboard USB-A port for operation. Use default credentials (username: `root`, password: `root`) to access the Debian desktop system.
### Advanced: Serial & SSH Login
The onboard Type-C USB port serves as the default debug UART (**115200 8n1**).
Use a serial tool to view kernel logs or log in directly via terminal.
For SSH access, expand network connectivity via USB Ethernet/WiFi dongles.
Note: The system only has the root superuser, and SSH password login is disabled by default for security. For temporary access, refer to [here](../m4n/FAQ.md)。
## Interactive Image Segmentation & Inpainting
A QT-based GUI for real-time segmentation (point/box selection) and inpainting.
![samqt](../../../zh/maixIV/assets/samqt.jpg)
Open Source Official GitHub Repo: [SAM-ONNX-AX650-CPP](https://github.com/AXERA-TECH/SAM-ONNX-AX650-CPP)
Download prebuilt binaries or compile from source.
Example: Removing a player from a photo:
<div><table><tr>
<td><img src="../../../zh/maixIV/assets/sam_example_before.png" alt=sam_example_before border=0></td>
<td><img src="../../../zh/maixIV/assets/sam_example_after.png" alt=sam_example_after border=0></td>
</tr></table></div>
Live Demo (Screenshots):
<div><table><tr>
<td><img src="../../../zh/maixIV/assets/sam_raw.jpg" alt=sam_raw border=0></td>
<td><img src="../../../zh/maixIV/assets/sam_sam.jpg" alt=sam_sam border=0></td>
<td><img src="../../../zh/maixIV/assets/sam_inpaint.jpg" alt=sam_inpaint border=0></td>
</tr><tr>
<td>RAW</td>
<td>SAM</td>
<td>Inpaint</td>
</tr></table></div>
## Interactive Text-to-Image Search (CLIP)
A QT-based GUI using OpenAI’s CLIP (Contrastive Language–Image Pre-training) for zero-shot image retrieval via text input (supports Chinese/English).
Open Source Official GitHub Repo: [CLIP-ONNX-AX650-CPP](https://github.com/AXERA-TECH/CLIP-ONNX-AX650-CPP)
[DEMO VIDEO](https://github.com/sipeed/sipeed_wiki/assets/13964381/df4cec7f-29af-465f-bfad-e54312274437)
1. Install QT:
```bash
apt update
apt install cmake qt6-base-dev
```
2. Download prebuilt files (executable, models, test images/text):
- [Baidu Pan](https://pan.baidu.com/s/17M5ugUyuf9mbi1cHLGJHXg)
3. Extract *CLIP.zip* to `/root/Desktop/`:
```bash
root@m4nhat-7190c7:~/Desktop/CLIP# tree -L 1
.
├── CLIPQT
├── cn_vocab.txt
├── coco_1000
├── libonnxruntime.so
├── libonnxruntime.so.1.16.0
├── onnx_models
├── run_en.sh
├── run_zh.sh
└── vocab.txt
```
4. Run in Desktop's terminal:
```bash
./run_zh.sh # For Chinese
./run_en.sh # For English
```
Screenshots:
![b38722991915fa54f17df18ca1f1447](https://github.com/AXERA-TECH/CLIP-ONNX-AX650-CPP/assets/13964381/8fa2c4b8-b061-413e-b72d-298bb4a445aa)
![34c8b68b1a8721d4ebff3b4b7184733](https://github.com/AXERA-TECH/CLIP-ONNX-AX650-CPP/assets/13964381/7d0b9740-3598-492c-ad42-2de23e7764e2)
## **Important Demo Pre-requisites**
HDMI0 (demo output) and HDMI1 (desktop) cannot operate simultaneously due to display driver limitations.
**To run demos:**
1. Terminate fb_vo process:
```bash
kill -9 $(pgrep fb_vo)
```
2. Connect display to HDMI0
3. Execute demo scripts via SSH/serial terminal
4. After demo, you can restore desktop:
```bash
/root/runVoHook.sh
```
## 32-Channel AI BOX (Person/Vehicle Detection)
BoxDemo showcases the complete pipeline from **H.264/H.265** decoding → AI analysis → HDMI display.
**Features:**
- Default: 32-channel display (6×6 layout)
- Dual HDMI support (mirror/extended)
- System power consumption <7W
- 3.6T NPU utilization (1/3 capacity)
- 15-20 FPS (CPU-bound)
**Configuration:**
- Edit /opt/bin/BoxDemo/box.conf:
- streamxx: RTSP source URLs
- DISP1=1: Enable HDMI1 output
**Run:**
```bash
bash /opt/bin/BoxDemo/run.sh
```
![aibox_pipeline](../../../zh/maixIV/assets/aibox_pipeline.png)
![aibox_example32ch](../../../zh/maixIV/assets/aibox_example32ch.png)
## DINO v2 Monocular Depth Estimation
Leveraging Facebook's DINO v2 model for relative depth estimation using single RGB camera.
![pipeline_bin](../../../zh/maixIV/assets/pipeline_bin.png)
**Execution:**
```bash
cd ~/ax-pipeline/bin
./sample_multi_demux_ivps_npu_multi_rtsp_hdmi_vo \
-p ./config/dinov2_depth.json \
-f ~/boxvideos/13.mp4
```
*Supports H.264 video files or RTSP streams*
**Results:**
<div><table><tr>
<td><img src="../../../zh/maixIV/assets/dinov2-1.png" alt=dinov2-1></td>
<td><img src="../../../zh/maixIV/assets/dinov2-2.png" alt=dinov2-2></td>
</tr></table></div>
![dinov2-3](../../../zh/maixIV/assets/dinov2-3.png)
## YOLOv5 Pedestrian Detection & Tracking
```bash
cd ~/ax-pipeline/bin
./sample_multi_demux_ivps_npu_multi_rtsp_hdmi_vo \
-p ./config/yolov5_seg.json \
-f ~/boxvideos/25.mp4
```
![yolov5_seg](../../../zh/maixIV/assets/yolov5_seg.png)

97
docs/hardware/en/maixIV/m4nhat/intro.md Normal file
View File

@@ -0,0 +1,97 @@
## Introduction
The M4N-Hat is a highly integrated AI computing module developed by Sipeed, featuring a compact design powered by AXERA's AX650N/C chip. As an embedded expansion module, it delivers 72 TOPS@INT4 (18 TOPS@INT8) computing power while retaining 8K video encoding/decoding capabilities, making it ideal for space-constrained edge computing applications.
This module supports plug-and-play compatibility with mainstream Raspberry Pi development boards and accelerates Transformer-based architectures. With its onboard 0.8mm 4-pin USB and Type-A USB SS 5Gbps interfaces, it enables quick expansion for peripherals like cameras and storage, making it perfect for smart cameras, industrial inspection, and other lightweight AI applications. The PCIE 2.0 expansion interface is fully compatible with Raspberry Pi 5, supporting multi-modal edge computing nodes and the deployment of quantized large models such as QWen 2.5, QWen 3, DeepSeek, and InternVL2.5.
## Showcase
<div style="display: flex; flex-wrap: wrap; gap: 10px; width: 100%;">
<img src="../../../zh/maixIV/assets/m4nhat/DSC07555.JPG" style="width: calc(50% - 5px);">
<img src="../../../zh/maixIV/assets/m4nhat/DSC07569.JPG" style="width: calc(50% - 5px);">
<img src="../../../zh/maixIV/assets/m4nhat/DSC07556.JPG" style="width: calc(50% - 5px);">
<img src="../../../zh/maixIV/assets/m4nhat/neofetch.jpg" style="width: calc(50% - 5px);">
</div>
## Key Specifications
| Component | Description |
| ------- | --------------------------------------------------- |
| CPU | 8x A55@1.7Ghz, integrated FPU, supports NEON acceleration |
| NPU | 72 TOPS@INT4 / 18 TOPS@INT8, supports INT4/INT8/INT16/FP16/FP32 inputs, TopN (N<=32) |
| CODEC | H.264/H.265 encoding/decoding, up to 8K@60fps decoding & 8K@30fps encoding |
| DSP | Dual-core 800MHz |
| RAM | 8GB 64-bit LPDDR4x (adjustable allocation: default 2GB system + 6GB AI CMM) |
| ROM | 32GB eMMC 5.1 (system storage) |
| Video Output | 1x HDMI 2.0a (max 4K@60fps) |
| Video Input| 11x 0.8mm 4-pin USB camera interface |
| PCIE | 1x 16-pin FPC (1-lane PCIE2.0 @5Gbps), Raspberry Pi 5 compatible |
| USB | 1x Type-A USB SS 5Gbps + 1x Type-C USB HS 480Mbps |
| Others | 1x 1.25mm 2-pin speaker, 1x 1.25mm 2-pin fan, 1x 10-pin FPC SPI display, 1x 6-pin FPC I2C touch |
## Performance Benchmarks
![](../../../zh/maixIV/assets/m4n/benchmark.png)
![](../../../zh/maixIV/assets/m4n/normalized_benchmark.png)
| Models | RK3588@6T| Maix4@18T | Hailo8 26T | Hailo8 13T |
|-------------|----------|------------|------------|------------|
| Inceptionv1 | 43 | 2494 | 928 | 519 |
| MobileNetv2 | 960 | 5073 | 2433 | 1738 |
| SqueezeNet11| 694 | 5961 | - | - |
| ResNet18 | 543 | 2254 | - | - |
| ResNet50 | 294 | 1045 | 1368 | 503 |
| SwinT | 21 | 401 | - | - |
| ViT-B/16 | 18 | 207 | 107 | 40 |
| YOLOv5s | 48 | 384 | 364 | 168 |
| YOLOv5n | 78 | 743 | - | - |
| YOLOv6s | 80 | 321 | - | - |
| YOLOv6n | 212 | 743 | - | - |
| YOLOv8s | 39 | 279 | - | - |
| YOLOv8n | 73 | 710 | - | - |
| YOLOxs | 34 | 304 | - | - |
| YOLO11s | 30 | 313 | - | - |
| Models | Item | Maix4@18T | RK3588@6T |
|------------------------------|------------------------------|--------------|--------------|
| SmolVLM-256M | Image Encoder 512*512 | 105ms | 842ms |
| | TTFT | 57ms | 87ms |
| | Decode | 80 tokens/s | 77 tokens/s |
| StableDiffusion 1.5(512*512) | U-Net | 0.43 s/it | 5.65 s/it |
| | VAE Decoder | 0.91 s | 11.13 s |
| Qwen2.5-VL-3B | Image Encoder 448*448 | 780 ms | |
| | TTFT 320 tokens | 2857 ms | |
| | Decode | 6.2 tokens/s | |
| | Image Encoder 392*392 | | 2930 ms |
| | TTFT 196 tokens | | 1262 ms |
| | Decode | | 8.6 tokens/s |
## Resources
### Hardware Documentation
Datasheet: https://dl.sipeed.com/shareURL/MaixIV/M4N-Dock
### Software Documentation
Docs: https://dl.sipeed.com/shareURL/MaixIV/M4N-Dock
SDK: https://www.ebaina.com/down/240000038900
### AI Development
LMM & AXCL: https://axcl-docs.readthedocs.io
Raspberry Pi 5 AXCL Guide: https://axcl-pi5-examples-cn.readthedocs.io
Model Hub: https://huggingface.co/AXERA-TECH
AI Toolchain (ONNX Conversion/Deployment)
- Pulsar2 (AXERA's ALL-IN-ONE Neural Network Compiler):
Docs: https://pulsar2-docs.readthedocs.io/en/latest/pulsar2/introduction.html
Download: https://pan.baidu.com/s/1FazlPdW79wQWVY-Qn--qVQ?pwd=sbru
op_support_list: https://pulsar2-docs.readthedocs.io/en/latest/appendix/op_support_list_ax650.html
Samples source: https://github.com/AXERA-TECH/ax-samples
LLM source: https://github.com/AXERA-TECH/ax-llm
## Technical Support
For custom development (kernel/OS customization, application-layer SDKs), contact: support@sipeed.

183
docs/hardware/en/maixIV/m4nhat/pcie-slaveboard.md Normal file
View File

@@ -0,0 +1,183 @@
# Installing M4N-Hat on Raspberry Pi 5
## Final Demo
After installation on Raspberry Pi 5, running the large language model QWen3 achieves 13.2 tokens/s (performance for smaller models is limited by PCIe link bandwidth, showing a gap compared to the standalone board's 19 tokens/s). Watch the demo video:
<video controls autoplay src="../../../zh/maixIV/assets/m4nhat/axcl-run-llm-on-raspi5-2025-07-03-4xspeedup.mp4" type="video/mp4"> Your browser does not support video playback. </video>
The video demonstrates:
1. Downloading the pre-supported QWen3-0.6B model
2. Setting up a Python virtual environment and installing required libraries
3. Running QWen3 and completing two Q&A sessions
## Installation
<div style="display: flex; justify-content: space-between;">
<img src="../../../zh/maixIV/assets/m4nhat/DSC07559.JPG" style="width: 48%;">
<img src="../../../zh/maixIV/assets/m4nhat/DSC07561.JPG" style="width: 48%;">
</div>
![](../../../zh/maixIV/assets/m4nhat/DSC07569.JPG)
## Flashing the M4N Slave System
1. Refer to the [System Flashing Guide](../m4n/system-update.html) and use AXDL to flash [AX650_card_V3.6.2_20250603154858_20250626183000.axp](https://dl.sipeed.com/MaixIV/M4N-Dock/09_Image/)。
2. Connect the M4N-Hat to the Raspberry Pi 5's PCIe slot using an FPC cable and secure it.
3. Power on the Raspberry Pi. Verify the accelerator card is detected with `lspci`:
```bash
# 应能看到以下输出
sipeed@raspberrypi:~$ lspci
0001:00:00.0 PCI bridge: Broadcom Inc. and subsidiaries BCM2712 PCIe Bridge (rev 21)
0001:01:00.0 Multimedia video controller: Axera Semiconductor Co., Ltd Device 0650 (rev01)
0002:00:00.0 PCI bridge: Broadcom Inc. and subsidiaries BCM2712 PCIe Bridge (rev 21)
0002:01:00.0 Ethernet controller: Raspberry Pi Ltd RP1 PCIe 2.0 South Bridge
```
The first two lines confirm PCIe initialization and detection of the Axera AX650 controller. ANd the `Multimedia video controller: Axera Semiconductor Co., Ltd Device 0650 (rev01)` has been mounted correctly.
**Troubleshooting PCIe Detection**
If the above output is missing, the PCIe x1 port may be disabled (default). Enable it via:
- Run `sudo raspi-config → 6 Advanced Options → A8 PCIe Speed → Select Yes` for PCIe x1 Gen3.
- or Manually add contents below to `/boot/firmware/config.txt`:
```bash
[all]
dtparam=pciex1_gen=3
```
Actually the `config.txt` file is located in the FAT32 type partition, so you can modify it after mount it on your PC directly.
> Note: Newly flashed Raspberry Pi SD cards lack the /boot/firmware directory. Boot once to generate it.
## Installing AXCL Software on Raspberry Pi 5
After PCIe detection, install the AXCL package for model acceleration:
```bash
$ sudo apt install axcl_host_aarch64_V3.6.2_20250603154858_NO4873.deb
```
Reboot the Pi. Verify installation with `axcl-smi`:
```bash
sipeed@raspberrypi:~$ axcl-smi
+------------------------------------------------------------------------------------------------+
| AXCL-SMI V3.6.2_20250603154858 Driver V3.6.2_20250603154858 |
+-----------------------------------------+--------------+---------------------------------------+
| Card Name Firmware | Bus-Id | Memory-Usage |
| Fan Temp Pwr:Usage/Cap | CPU NPU | CMM-Usage |
|=========================================+==============+=======================================|
| 0 AX650N V3.6.2 | 0001:01:00.0 | 148 MiB / 945 MiB |
| -- 55C -- / -- | 0% 0% | 18 MiB / 7040 MiB |
+-----------------------------------------+--------------+---------------------------------------+
+------------------------------------------------------------------------------------------------+
| Processes: |
| Card PID Process Name NPU Memory Usage |
|================================================================================================|
sipeed@raspberrypi:~$
```
## Testing AXCL Model Inference
Run `axcl_run_model` (usage mirrors native ax_run_model). Example with YOLOv5s (single-core model; full-core performance scales ~3x):
```bash
sipeed@raspberrypi:~$ axcl_run_model -m yolov5s.axmodel
Run AxModel:
model: yolov5s.axmodel
type: 1 Core
vnpu: Disable
warmup: 1
repeat: 1
batch: { auto: 1 }
axclrt ver: 1.0.0
pulsar2 ver: 1.2-patch2 7e6b2b5f
tool ver: 0.0.1
cmm size: 12730188 Bytes
------------------------------------------------------
min = 7.837 ms max = 7.837 ms avg = 7.837 ms
------------------------------------------------------
```
Performance Benchmarks Table：
| Model | Input Size | Batch 1 (IPS) | Batch 8 (IPS) |
|---------------|------------|---------------|---------------|
| Inceptionv1 | 224 | 1073 | 2494 |
| Inceptionv3 | 224 | 478 | 702 |
| MobileNetv1 | 224 | 1508 | 4854 |
| MobileNetv2 | 224 | 1366 | 5073 |
| ResNet18 | 224 | 1066 | 2254 |
| ResNet50 | 224 | 576 | 1045 |
| SqueezeNet11 | 224 | 1560 | 5961 |
| Swin-T | 224 | 342 | 507 |
| ViT-B/16 | 224 | 162 | 207 |
| YOLOv5s | 640 | 326 | 394 |
| YOLOv6s | 640 | 282 | 322 |
| YOLOv8s | 640 | 248 | 279 |
| YOLOv9s | 640 | 237 | - |
| YOLOv10s | 640 | 298 | - |
| YOLOv11n | 640 | 860 | - |
| YOLOv11s | 640 | 305 | - |
| YOLOv11m | 640 | 114 | - |
| YOLOv11l | 640 | 87 | - |
| YOLOv11x | 640 | 41 | - |
## AXCL Advanced Usage
- [AXCL Documentation](https://axcl-docs.readthedocs.io)
- [RPi 5 AXCL Guide](https://axcl-pi5-examples-cn.readthedocs.io)
- Refer to [here](../m4n/axmodel-deploy.html) for detailed model development.
## Known Issues
### M4N-Hat Fails to Mount After Soft Reboot RPI5
Due to PCIe reset timing limitations, cold boot (power cycle) is required for successful mounting. A soft reboot leaves PCIe link down (line 18):
```bash
7.11 fs_open: 'armstub8-2712.bin'
7.15 Loading 'kernel_2712.img' to 0x00000000 offset 0x200000
7.33 Read kernel_2712.img bytes 9727677 hnd 0x3c43
9.93 PCI1 reset
9.03 PCI2 reset
9.13 set_reboot_order 0
9.13 set_reboot_arg1 0
9.14 USB-OTG disconnect
9.56 MESS:00:00:09.256590:0: Starting OS 9256 ms
9.62 MESS:00:00:09.262115:0: 00000040: -> 00000480
9.63 MESS:00:00:09.263966:0: 00000030: -> 00100080
9.68 MESS:00:00:09.268679:0: 00000034: -> 00100080
9.73 MESS:00:00:09.273392:0: 00000038: -> 00100080
9.78 MESS:00:00:09.278105:0: 0000003c: -> 00100080
NOTICE: BL31: v2.6(release):v2.6-240-gfc45bc492
NOTICE: BL31: Built : 12:55:13, Dec 4 2024
[ 0.695249] brcm-pcie 1000110000.pcie: link down
Debian GNU/Linux 12 raspberrypi ttyAMA10
My IP address is 192.168.10.176 fdae:b0ae:ebf1:0:b270:135e:b646:70c3
raspberrypi login:
```
**Workaround:**
Before rebooting, reset the M4N-Hat via GPIO:
```bash
gpioset gpiochip0 28=0 # Force M4N-Hat reset
reboot
```

157
docs/hardware/en/maixIV/m4nhat/quick-start.md Normal file
View File

@@ -0,0 +1,157 @@
## System Update
For details, refer to the [Flashing OS Image](../m4n/system-update.html)，The TFCard&eMMC image (Debian 12) is recommended.
The following instructions are based on this image. If using a custom-built image, pay attention to operational details.
## System Boot
### Pre-Boot Preparation
1. 5V USB power supply
2. mini HDMI cable and display
3. USB serial tool (e.g., [SLogic Combo8](../../logic_analyzer/combo8/index.html) (optional, for debugging/login))
### Normal Boot
<div style="display: flex; flex-wrap: wrap; gap: 10px; width: 100%;">
<img src="../../../zh/maixIV/assets/m4nhat/DSC07545.JPG" style="width: calc(50% - 5px);">
<img src="../../../zh/maixIV/assets/m4nhat/DSC07546.JPG" style="width: calc(50% - 5px);">
</div>
1. Login Interface
- Connect a display via mini HDMI and power on. The core board’s blue LED and Hat baseboard’s white LED should light up, indicating normal power supply.
- If the eMMC contains the default Raspberry Pi slave image, flash a new standalone image to the TF card and insert it into the M4N-Hat.
- Press and hold the `BOOT0` button, then press `RST`. After ~20 seconds, the LightDM login screen will appear, indicating a successful boot.
2. Xfce4 Desktop
- Connect a mouse/keyboard to the onboard USB-A port for input.
- Default credentials: Username: `root`, Password: `root`.
### Advanced: Serial & SSH Login
The onboard Type-C USB port serves as the default debug UART (**115200 8n1**).
Use a serial tool to view kernel logs or log in directly via terminal.
For SSH access, expand network connectivity via USB Ethernet/WiFi dongles.
Note: The system only has the root superuser, and SSH password login is disabled by default for security. For temporary access, refer to [here](../m4n/FAQ.md)。
## LLM
### DeepSeek-R1 & QWen3
Left: [DeepSeek-R1 1.5B](https://huggingface.co/AXERA-TECH/DeepSeek-R1-Distill-Qwen-1.5B)
Right: [QWen3 0.6B](https://huggingface.co/AXERA-TECH/Qwen3-0.6B)
Deployment guide: [here](../m4n/axmodel-deploy.html#部署大语言、多模态模型)
![DSr1-1.5B-and-QWen-0.6B](../../../zh/maixIV/assets/m4nhat/DSr1-1.5B-and-QWen-0.6B.jpg)
## VLM
### internVL3
![internVL3-demo](../../../zh/maixIV/assets/m4nhat/internVL3-demo.jpg)
Demo video:
<video controls autoplay src="../../../zh/maixIV/assets/m4nhat/m4nhat-run-llm-internVL-2025-07-07.mp4" type="video/mp4"> Your browser does not support video playback. </video>
## DepthAnything v2
1. Download the [axcl npu python library](https://github.com/AXERA-TECH/pyaxengine/releases)
2. Install: `pip install axengine-x.y.z-py3-none-any.whl`.
3. Run:
```bash
source ../venv-llm/bin/activate
python python/infer.py --img examples/demo02.jpg --model depth_anything_v2_vits_ax650.axmodel
```
![DepthAnything-v2-before](../../../zh/maixIV/assets/m4nhat/DSC07539.JPG)
![DepthAnything-v2-after](../../../zh/maixIV/assets/m4nhat/DSC07540.JPG)
![depthanything-output](../../../zh/maixIV/assets/m4nhat/depthanything-output.png)
## Interactive Image Segmentation & Inpainting
A QT-based GUI for real-time segmentation (point/box selection) and inpainting.
![samqt](../../../zh/maixIV/assets/samqt.jpg)
Open Source Official GitHub Repo: [SAM-ONNX-AX650-CPP](https://github.com/AXERA-TECH/SAM-ONNX-AX650-CPP)
Download prebuilt binaries or compile from source.
Example: Removing a player from a photo:
<div><table><tr>
<td><img src="../../../zh/maixIV/assets/sam_example_before.png" alt=sam_example_before border=0></td>
<td><img src="../../../zh/maixIV/assets/sam_example_after.png" alt=sam_example_after border=0></td>
</tr></table></div>
Live Demo (Screenshots):
<div><table><tr>
<td><img src="../../../zh/maixIV/assets/sam_raw.jpg" alt=sam_raw border=0></td>
<td><img src="../../../zh/maixIV/assets/sam_sam.jpg" alt=sam_sam border=0></td>
<td><img src="../../../zh/maixIV/assets/sam_inpaint.jpg" alt=sam_inpaint border=0></td>
</tr><tr>
<td>RAW</td>
<td>SAM</td>
<td>Inpaint</td>
</tr></table></div>
## Interactive Text-to-Image Search (CLIP)
A QT-based GUI using OpenAI’s CLIP (Contrastive Language–Image Pre-training) for zero-shot image retrieval via text input (supports Chinese/English).
Open Source Official GitHub Repo: [CLIP-ONNX-AX650-CPP](https://github.com/AXERA-TECH/CLIP-ONNX-AX650-CPP)
[DEMO VIDEO](https://github.com/sipeed/sipeed_wiki/assets/13964381/df4cec7f-29af-465f-bfad-e54312274437)
1. Install QT:
```bash
apt update
apt install cmake qt6-base-dev
```
2. Download prebuilt files (executable, models, test images/text):
- [Baidu Pan](https://pan.baidu.com/s/17M5ugUyuf9mbi1cHLGJHXg)
3. Extract *CLIP.zip* to `/root/Desktop/`:
```bash
root@m4nhat-7190c7:~/Desktop/CLIP# tree -L 1
.
├── CLIPQT
├── cn_vocab.txt
├── coco_1000
├── libonnxruntime.so
├── libonnxruntime.so.1.16.0
├── onnx_models
├── run_en.sh
├── run_zh.sh
└── vocab.txt
```
4. Run in Desktop's terminal:
```bash
./run_zh.sh # For Chinese
./run_en.sh # For English
```
Screenshots:
![b38722991915fa54f17df18ca1f1447](https://github.com/AXERA-TECH/CLIP-ONNX-AX650-CPP/assets/13964381/8fa2c4b8-b061-413e-b72d-298bb4a445aa)
![34c8b68b1a8721d4ebff3b4b7184733](https://github.com/AXERA-TECH/CLIP-ONNX-AX650-CPP/assets/13964381/7d0b9740-3598-492c-ad42-2de23e7764e2)

31
docs/hardware/en/sidebar.yaml
View File

@@ -107,6 +107,37 @@ items:
url: /ai/en/deploy/ax-pi.html
- label: Questions (FAQ)
file: maixIII/ax-pi/faq_axpi.md
- label: Maix-IV
items:
- label: Maix M4N
# file: maixIV/m4n/m4n.md
items:
- label: Flashing OS Image
file: maixIV/m4n/system-update.md
- label: AI Models Deployment
file: maixIV/m4n/axmodel-deploy.md
- label: FAQ
file: maixIV/m4n/FAQ.md
- label: Maix M4N-Dock
items:
- label: Intro
file: maixIV/m4ndock/intro.md
- label: Flashing OS Image
file: maixIV/m4n/system-update.md
- label: Quick Start
file: maixIV/m4ndock/quick-start.md
- label: FAQ
file: maixIV/m4ndock/FAQ.md
- label: Maix M4N-Hat
items:
- label: Intro
file: maixIV/m4nhat/intro.md
- label: Flashing OS Image
file: maixIV/m4n/system-update.md
- label: Quick Start
file: maixIV/m4nhat/quick-start.md
- label: RPI5 PCIe Card
file: maixIV/m4nhat/pcie-slaveboard.md
- label: MaixCAM
items:
- label: MaixCAM