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 排线接口和供电/触摸相关接口。连接时需要注意排线方向、连接器锁扣状态以及屏幕供电方式。

接口连接

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

连接注意事项：

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

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

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

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

快速开始

1. 关闭开发板电源。

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

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

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

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

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 桌面显示效果：

功能使用

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

调整屏幕亮度和音量

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

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

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

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

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

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

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 目录：

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

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

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

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

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

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

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

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 命令行播放视频的效果图。

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

音频播放功能的使用方法

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

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

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

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

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

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

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

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

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 命令行播放音频的效果图。

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

音频输出检查

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

pactl info

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

进阶功能

自动显示模式

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

命令行状态查看

常用排查命令如下：

# 查看 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 查看默认输出设备；确认音频设备已连接，并确认音量未静音。