MIPI

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

---

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

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

M1 / L1 接口连接

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

连接注意事项：

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

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

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

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

快速开始

1. 关闭开发板电源。

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

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

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

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

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

M1 查看显示与背光状态：

L1 MIPI 桌面显示效果：

L1 查看显示与背光状态：

功能使用（GNOME）

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

调整屏幕亮度和音量

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

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

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

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

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

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

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

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命令行操作的视频播放功能：在使用命令行播放视频时，可输入以下命令。

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命令行操作的音频播放功能：在使用命令行播放时，可输入以下命令。

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

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

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

音频输出检查

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

pactl info

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

功能使用（Weston）

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

触摸功能

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

视频播放功能的使用方法

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

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

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

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 屏幕可正常显示居中视频窗口。

音频播放功能的使用方法

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

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

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

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

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

进阶功能

自动显示模式

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

命令行状态查看

常用排查命令如下：

# 查看背光节点
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 同时连接或接口切换后未重新启动	仅保留目标显示接口连接，断电后重新上电启动系统。