# MIPI

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

---

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

# 概述

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

Quectel Pi M2 显示相关接口如下表所示：

| **接口** | **说明** |
| --- | --- |
| MIPI-DSI | 1 路 FPC 座，基于 MIPI 标准。本文示例屏幕实测显示模式为 `1280x800`。 |
| 触摸 | 示例屏幕通过屏幕转接板/排线与系统建立触摸输入，连接完成后可直接在 Debian 桌面中使用。 |

# 硬件接口

## 屏幕接口说明

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

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

## 接口连接

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

```{image} images/image_E9cybzT2koLPKIxUVBWczXkHnOn.webp
:width: 1653px
:height: 857px
```

连接注意事项：

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

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

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

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

# 快速开始

1. 关闭开发板电源。

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

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

4. 系统启动后进入 Debian 桌面。系统默认进入 GNOME 桌面。

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

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

实测 MIPI 显示状态为 `connected`，显示模式为 `1280x800`。实测背光节点为 `/sys/class/backlight/0-0045/`，当前亮度为 `199`，最大亮度为 `255`。

MIPI 桌面显示效果：

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

# 功能使用

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

## 调整屏幕亮度和音量

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

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

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

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

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

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

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

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

## 触摸功能

连接 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_BQoEbpzVioF3I6xRncocVhkHn8f.webp
:width: 1280px
:height: 800px
```

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

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

> 💡 建议在开发板图形桌面终端中执行以下播放命令。若通过 ADB root shell 执行，可能因缺少图形桌面和音频会话环境变量而无法正常播放。

在开发板图形桌面终端中（已登录 `q` 用户），可直接执行：

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

若通过 ADB root shell 或 SSH root 登录执行，需先切换到 `q` 用户，再依次设置图形桌面会话环境变量，最后执行播放命令：

```bash
su - q
export DISPLAY=:0
export WAYLAND_DISPLAY=wayland-0
export XDG_RUNTIME_DIR=/run/user/1000
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
gst-launch-1.0 playbin uri=file:///home/q/Videos/m1-mipi-display-test.mp4
```

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

```{image} images/image_XCkUbKMOTo9aC3xzqukcYDb5nlf.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_FN19blCF9oOMVvx5j2DcCLxMnhd.webp
:width: 1280px
:height: 800px
```

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

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

> 💡 建议在开发板图形桌面终端中执行以下播放命令。若通过 ADB root shell 执行，可能因缺少音频会话环境变量而无法正常播放音频。

在开发板图形桌面终端中（已登录 `q` 用户），可直接执行：

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

若通过 ADB root shell 或 SSH root 登录执行，需先切换到 `q` 用户，再依次设置音频会话环境变量，最后执行播放命令：

```bash
su - q
export DISPLAY=:0
export WAYLAND_DISPLAY=wayland-0
export XDG_RUNTIME_DIR=/run/user/1000
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
gst-launch-1.0 playbin uri=file:///home/q/Music/m1-mipi-audio-test.mp3
```

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

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

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

## 音频输出检查

视频播放无声音时，可在开发板图形桌面终端中查看音频服务和默认输出设备：

```bash
pactl info
```

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

# 进阶功能

## 自动显示模式

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

## 命令行状态查看

常用排查命令如下：

```bash
# 查看 DRM 显示接口
ls /sys/class/drm/

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

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

# 查看背光亮度和最大亮度
cat /sys/class/backlight/0-0045/brightness
cat /sys/class/backlight/0-0045/max_brightness

# 查看音频服务和默认输出设备
pactl info

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

# 应用场景

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

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

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

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

# 疑难解答

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