# MIPI

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本文档介绍 **Quectel Pi M1 / L1 Debian** 系统下 **MIPI-DSI** 显示屏的连接、识别、亮度调节、触摸使用和视频播放方法。本文以微雪 **8-inch DSI LCD (C)** 电容触摸屏为例进行说明。

> 💡 **说明**：Quectel Pi M1 / L1 的 **Micro HDMI** 与 **MIPI-DSI** 显示为二选一使用方式，不能同时作为双屏显示输出。切换显示接口后，建议重新上电启动系统。

# 概述

**MIPI-DSI** 是一种面向显示屏的高速串行显示接口，适用于嵌入式桌面、触摸交互终端、工业 HMI 和媒体播放等场景。Quectel Pi M1 / L1 提供 1 路 MIPI-DSI 显示接口，可连接配套 DSI 屏幕进入 Debian 桌面环境。M1 默认进入 GNOME 桌面，L1 默认进入 Weston 桌面。

Quectel Pi M1 / L1 显示相关接口如下表所示：

| **接口** | **说明** |
| --- | --- |
| MIPI-DSI (M1) | 1 路 FPC 座，基于 MIPI 标准，支持 FHD+（1080 × 2520）@ 60 fps。 |
| MIPI-DSI (L1) | 1 路FPC 座，基于 MIPI 标准，支持 HD+ (1680 x 720) @ 60 fps。 |
| 触摸 | 示例屏幕通过屏幕转接板/排线与系统建立触摸输入，连接完成后可直接在 Debian 桌面中使用。 |

# 硬件接口

## 屏幕接口说明

微雪 8-inch DSI LCD (C) 屏幕背面包含 DSI 排线接口和供电/触摸相关接口。连接时需要注意排线方向、连接器锁扣状态以及屏幕供电方式。

```{image} images/image_BTpLbyXSYoG1K8xSk4Jc3VJanSd.webp
:width: 3264px
:height: 2324px
```

## M1 / L1 接口连接

将 MIPI-DSI 排线连接到 Quectel Pi M1 / Quectel Pi L1 的 MIPI-DSI FPC 接口，并确认排线插入到位、锁扣压紧。屏幕供电请按照屏幕硬件说明连接，避免在设备上电状态下插拔 MIPI 排线。

```{image} images/image_RMQybgBqBohQgfxUJI1cGLN2n8b.webp
:width: 1956px
:height: 901px
```

连接注意事项：

1. 连接或拆卸 MIPI 排线前，请先关闭开发板电源。

2. 确认排线金手指方向正确，避免反插。

3. 确认 FPC 座锁扣已经压紧，避免开机后黑屏或触摸异常。

4. 若屏幕需要独立供电，请确认供电接口连接稳定。

# 快速开始

1. 关闭开发板电源。

2. 按照硬件连接说明接入 MIPI-DSI 屏幕。

3. 接通屏幕供电，并给开发板上电。

4. 系统启动后进入 Debian 桌面。M1 进入 GNOME 桌面，L1 进入 Weston 桌面。

5. 如需确认系统状态，可在开发板终端执行：

```bash
hostname -I
cat /sys/class/drm/card0-DSI-1/status
cat /sys/class/drm/card0-DSI-1/modes
cat /sys/class/backlight/2-0045/brightness
cat /sys/class/backlight/2-0045/max_brightness
```

M1 实测背光节点为 `/sys/class/backlight/3-0045/`，L1 实测背光节点为 `/sys/class/backlight/2-0045/`，当前亮度和最大亮度均为 `255`。

M1 MIPI 桌面显示效果：

```{image} images/image_LBdfb5f43ohz0cx4l82c6MV5ngs.webp
:width: 1280px
:height: 800px
```

M1 查看显示与背光状态：

```{image} images/image_OAqJbV9cpoJCHAxcvsQc5F2InPg.webp
:width: 1280px
:height: 800px
```

L1 MIPI 桌面显示效果：

```{image} images/image_DFPjbl8Nqo3MZhx8YOUcqNjMnrc.webp
:width: 760px
:height: 427px
```

L1 查看显示与背光状态：

```{image} images/image_Abm9btZ3pohFrfxE2Hkc38iFnih.webp
:width: 1280px
:height: 800px
```

# 功能使用（GNOME）

以下功能基于 M1 GNOME 桌面环境。

## 调整屏幕亮度和音量

在连接 MIPI 屏幕并进入 Debian 桌面后，点击桌面右上角状态栏区域，可在快捷设置面板中拖动音量栏和亮度栏，调整当前音频输出音量和屏幕亮度。

```{image} images/image_GnFsbc8VdoaJ6IxoajVcnQ3MnZc.webp
:width: 1280px
:height: 800px
```

除桌面快捷设置外，MIPI 屏幕亮度也可通过系统背光节点查看。本文实测背光节点为 `/sys/class/backlight/3-0045/`：

```bash
cat /sys/class/backlight/3-0045/brightness
cat /sys/class/backlight/3-0045/max_brightness
```

如需临时调整亮度，可在开发板上执行以下命令。示例将亮度设置为 `200`：

```bash
echo 200 | sudo tee /sys/class/backlight/3-0045/brightness
```

如需恢复最大亮度，可执行：

```bash
cat /sys/class/backlight/3-0045/max_brightness
sudo sh -c 'cat /sys/class/backlight/3-0045/max_brightness > /sys/class/backlight/3-0045/brightness'
```

> 💡 **注意**：不同系统版本的背光节点名称可能不同。如 `/sys/class/backlight/3-0045/` 不存在，可先执行 `ls /sys/class/backlight/` 查看实际节点名称。

## 触摸功能

连接 MIPI 屏幕并进入 Debian 桌面后，可直接使用屏幕触摸功能进行点击、滑动和窗口操作。若触摸无响应，请优先检查屏幕触摸连接线、供电和 I2C/触摸相关连接是否牢固。

## 视频播放功能的使用方法

可先将测试视频推送到开发板的 `Videos` 目录：

```bash
adb push /home/q/work/temp/test-1.mp4 /home/q/Videos/m1-mipi-display-test.mp4
```

**可视化界面的视频播放功能**：在 Debian 桌面中，可通过文件管理器进入 `Videos` 目录，双击 `m1-mipi-display-test.mp4` 进行播放。

```{image} images/image_NHGHbOBOeoOkOCxhvFvcty1Nnzc.webp
:width: 1280px
:height: 800px
```

```{image} images/image_XIK9bifbboecXOxeI4dcWKHnnhd.webp
:width: 1280px
:height: 800px
```

**GStreamer命令行操作的视频播放功能**：在使用命令行播放视频时，可输入以下命令。

```bash
gst-launch-1.0 playbin uri=file:///home/q/Videos/m1-mipi-display-test.mp4
```

以下为 GStreamer 命令行播放视频的效果图。

```{image} images/image_EkkIbLz9lokqWSx59rJcaOjLnJh.webp
:width: 1280px
:height: 800px
```

本文实测通过桌面文件管理器和 GStreamer 命令行方式播放视频，MIPI 屏幕可正常显示画面。

## 音频播放功能的使用方法

可先将测试音频推送到开发板的 `Music` 目录：

```bash
adb push /home/q/work/temp/test.mp3 /home/q/Music/m1-mipi-audio-test.mp3
```

**可视化界面的音频播放功能**：在 Debian 桌面中，可通过文件管理器进入 `Music` 目录，双击 `m1-mipi-audio-test.mp3` 进行播放。

```{image} images/image_Y6SNbKXZFo5zlbxPsgscskSQnfd.webp
:width: 1280px
:height: 800px
```

```{image} images/image_TepebCAl1o9KjyxjiQGcv5Bjnkd.webp
:width: 1280px
:height: 800px
```

**GStreamer命令行操作的音频播放功能**：在使用命令行播放时，可输入以下命令。

```bash
gst-launch-1.0 playbin uri=file:///home/q/Music/m1-mipi-audio-test.mp3
```

以下为 GStreamer 命令行播放音频的效果图。

```{image} images/image_Iz7BbfIIAoeRs7xR4DycBFntnTd.webp
:width: 1280px
:height: 800px
```

本文实测通过桌面文件管理器和 GStreamer 命令行方式播放音频，当前音频输出设备可正常播放声音。若使用外接蓝牙音箱或其它音频设备，请确认系统声音输出设备已选择正确。

## 音频输出检查

视频播放无声音时，可先查看音频服务和默认输出设备：

```bash
pactl info
```

若系统中存在多个音频输出设备，可在 GNOME 桌面右上角快捷设置中切换输出设备，或进入 **Settings > Sound** 查看音频输出配置。

# 功能使用（Weston）

以下功能基于 L1 Weston 桌面环境。

## 触摸功能

连接 MIPI 屏幕并进入 Debian 桌面后，可直接使用屏幕触摸功能进行点击、滑动和窗口操作。若触摸无响应，请优先检查屏幕触摸连接线、供电和 I2C/触摸相关连接是否牢固。

## 视频播放功能的使用方法

可先将测试视频从主机推送到开发板的 `Videos` 目录：

```bash
adb push /home/q/work/temp/test-1.mp4 /home/q/Videos/l1-mipi-display-test.mp4
```

**GStreamer命令行操作的视频播放功能**：在 Weston 桌面中使用命令行播放视频时，可输入以下命令。

```bash
export XDG_RUNTIME_DIR=/run/user/root
export WAYLAND_DISPLAY=wayland-1
gst-launch-1.0 playbin uri=file:///home/q/Videos/l1-mipi-display-test.mp4 video-sink="waylandsink fullscreen=false x=160 y=128 width=960 height=544" audio-sink=pulsesink
```

> 💡 **说明**：本文实测环境中 Weston 以 `root` 用户启动，Wayland socket 为 `/run/user/root/wayland-1`，因此命令行播放视频时需要设置 `XDG_RUNTIME_DIR=/run/user/root` 和 `WAYLAND_DISPLAY=wayland-1`。上述命令通过 `videoscale` 和 `waylandsink` 将画面输出为 960x544 居中窗口显示。若你的 Weston 运行在其它用户、其它 socket 或其它分辨率下，请以实际环境为准调整。

本文实测通过 GStreamer 命令行方式播放视频，MIPI 屏幕可正常显示居中视频窗口。

```{image} images/image_GJXWbVywYom8uIxHAfocp3wQnsc.webp
:width: 1280px
:height: 800px
```

## 音频播放功能的使用方法

可先将测试音频从主机推送到开发板的 `Music` 目录：

```bash
adb push /home/q/work/temp/test.mp3 /home/q/Music/l1-mipi-audio-test.mp3
```

**GStreamer命令行操作的音频播放功能**：在使用命令行播放时，可输入以下命令。

```bash
gst-launch-1.0 playbin uri=file:///home/q/Music/l1-mipi-audio-test.mp3
```

本文实测通过 GStreamer 命令行方式播放音频，当前音频输出设备可正常播放声音。实测时已连接蓝牙耳机，PulseAudio 默认输出设备为 `bluez_sink.*.a2dp_sink`。若使用外接蓝牙音箱、蓝牙耳机或其它音频设备，请确认系统声音输出设备已选择正确。

```{image} images/image_YkXnb7VK6ogJrOxEYZYc8leFnCd.webp
:width: 1119px
:height: 511px
```

# 进阶功能

## 自动显示模式

MIPI 屏幕连接后，系统会在启动阶段加载显示驱动并输出桌面画面。由于 MIPI-DSI 不是面向热插拔的接口，建议在关机状态下完成排线连接后再开机。

## 命令行状态查看

常用排查命令如下：

```bash
# 查看背光节点
ls /sys/class/backlight/

# 查看 MIPI/DSI 连接状态和显示模式
cat /sys/class/drm/card0-DSI-1/status
cat /sys/class/drm/card0-DSI-1/modes

# 查看背光亮度（M1 背光节点为 3-0045，L1 为 2-0045）
cat /sys/class/backlight/3-0045/brightness
cat /sys/class/backlight/3-0045/max_brightness

# 查看系统日志中的显示相关信息
journalctl -b | grep -Ei 'dsi|mipi|drm|panel|backlight'
```

# 应用场景

- **媒体娱乐终端**：通过 MIPI 屏幕播放视频、音乐或展示图片。

- **工业数据可视化平台**：用于显示设备状态、传感器数据、仪表盘和告警信息。

- **智能交互终端**：结合触摸屏实现本地菜单、控制面板和人机交互界面。

- **开发调试显示终端**：在无需额外 HDMI 显示器的情况下查看 Debian 桌面和调试信息。

# 疑难解答

| **现象** | **可能原因** | **处理方法** |
| --- | --- | --- |
| 开机后黑屏 | MIPI排线未插紧、方向错误、屏幕供电异常，或系统未正确加载显示驱动 | 断电后重新检查排线方向、FPC锁扣和屏幕供电；重新上电后通过串口或ADB查看系统日志。 |
| 屏幕花屏或闪烁 | 排线接触不良、排线质量不佳、屏幕供电不稳定或受到干扰 | 重新插拔并固定排线，检查供电，避免排线靠近强干扰源。 |
| 触摸无响应 | 触摸相关连接未接好，或触摸驱动未正常加载 | 检查屏幕触摸连接线和供电；通过系统日志查看触摸/I2C相关报错。 |
| 亮度不可调 | 背光节点名称与本文示例不同，或当前系统未暴露背光调节接口 | 执行 `ls /sys/class/backlight/` 查看实际节点，并使用实际节点路径读取或写入亮度值。 |
| 视频无法播放 | 视频编码不受当前播放器支持，或文件路径错误 | 确认视频文件已存在于 `/home/q/Videos/`；M1 尝试使用 GNOME 视频播放器或 GStreamer；L1 尝试使用 GStreamer 命令行播放常见 H.264 MP4 测试视频。 |
| 视频有画面无声音 | 音频输出设备选择错误、音量被静音，或音频设备未连接 | M1 检查右上角声音设置，执行 `pactl info` 查看默认输出设备；L1 确认音频设备已连接，并确认音量未静音。 |
| 切换显示接口后无画面 | MIPI 与 Micro HDMI 同时连接或接口切换后未重新启动 | 仅保留目标显示接口连接，断电后重新上电启动系统。 |