Skip to content

docs(dragon/q6a): add troubleshooting for 8-inch DSI overlay boot failure issue #1591

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tangzz-radxa wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(dragon/q6a): add troubleshooting for 8-inch DSI overlay boot failure issue #1591

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1311733
docs(dragon/q6a): add troubleshooting for 8-inch DSI overlay boot fai…
tangzz-radxa Apr 4, 2026
5be71f8
docs(dragon/q6a): add English translations for DSI overlay troublesho…
tangzz-radxa Apr 4, 2026
8fd4ec9
fix: remove incorrectly placed English files from docs/i18n directory
tangzz-radxa Apr 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions docs/dragon/q6a/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,3 +136,30 @@ vim /usr/share/glib-2.0/schemas/org.gnome.settings-daemon.plugins.power.gschema.

- 系统会以 `EL2` 而不是 `EL1` 启动，此时**可以**使用 KVM
- `/dev/mtd0` 会消失，因此不能直接在板子上更新 SPI 固件

## 为什么启用 8-inch DSI overlay 后 Q6A 无法启动？

部分用户在 Dragon Q6A 上启用 Radxa Display 8 HD 的 DSI overlay 后遇到启动失败问题（蓝灯常亮后闪烁，无显示输出）。

这是一个已知的兼容性问题，与特定内核版本相关：

**已知受影响版本：**
- `linux-image-6.18.2-3-qcom` 及更早版本

**解决方案：**
1. 检查当前内核版本：
```bash
apt policy linux-image-6.18.2-4-qcom
```
2. 如果 `linux-image-6.18.2-4-qcom` 可用，更新系统：
```bash
sudo apt update
sudo apt upgrade
```
3. 重启系统后再次尝试启用 DSI overlay

**如果问题仍然存在：**
- 请暂时禁用 DSI overlay，等待 [linux-qcom](https://github.com/radxa-pkg/linux-qcom/releases) 发布修复版本
- 可以通过串口或恢复模式访问系统来禁用 overlay

**注意：** 此问题仅影响 Radxa Display 8 HD 的 DSI overlay，HDMI 输出和其他功能不受影响。
30 changes: 30 additions & 0 deletions docs/dragon/q6a/hardware-use/mipi-dsi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,33 @@ sidebar_position: 11
## 接口引脚定义

可以参考 [资源汇总下载](../download) 页面的硬件原理图。

## 已知问题与解决方案

### Radxa Display 8 HD 启动问题

部分用户在启用 Radxa Display 8 HD 的 DSI overlay 后遇到启动失败问题（蓝灯常亮后闪烁，无显示输出）。

**原因：**
这是一个已知的兼容性问题，与特定内核版本相关。

**受影响版本：**
- `linux-image-6.18.2-3-qcom` 及更早版本

**解决方案：**
1. 检查当前内核版本：
```bash
apt policy linux-image-6.18.2-4-qcom
```
2. 如果 `linux-image-6.18.2-4-qcom` 可用，更新系统：
```bash
sudo apt update
sudo apt upgrade
```
3. 重启系统

**如果问题仍然存在：**
- 请暂时禁用 DSI overlay，等待 [linux-qcom](https://github.com/radxa-pkg/linux-qcom/releases) 发布修复版本
- 可以通过串口或恢复模式访问系统来禁用 overlay

**注意：** 此问题仅影响 Radxa Display 8 HD 的 DSI overlay，Radxa Display 10 FHD 和其他功能不受影响。
146 changes: 21 additions & 125 deletions i18n/en/docusaurus-plugin-content-docs/current/dragon/q6a/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,135 +2,31 @@
sidebar_position: 145
---

# Frequently Asked Questions (FAQ)
# Frequently Asked Questions

## Failed to Open Serial Port Device
## Why does enabling 8-inch DSI overlay cause Q6A boot failure?

If you encounter the error `Error: Permission denied, cannot open /dev/ttyUSB0` when trying to open the serial port!
Some users have encountered boot failure issues (blue light stays on then blinks, no display output) after enabling the Radxa Display 8 HD DSI overlay on Dragon Q6A.

You can troubleshoot the issue by following these steps:
This is a known compatibility issue related to specific kernel versions:

1. Check if the serial device is properly connected to the PC
**Known affected versions:**
- `linux-image-6.18.2-3-qcom` and earlier versions

2. Check serial device permissions
**Solution:**
1. Check current kernel version:
```bash
apt policy linux-image-6.18.2-4-qcom
```
2. If `linux-image-6.18.2-4-qcom` is available, update the system:
```bash
sudo apt update
sudo apt upgrade
```
3. Reboot the system and try enabling DSI overlay again

For Linux systems, if the serial device has insufficient permissions, you need to run the following commands in the terminal to grant the current user access to the device.
**If the issue persists:**
- Temporarily disable DSI overlay and wait for [linux-qcom](https://github.com/radxa-pkg/linux-qualcomm/releases) to release a fix
- You can access the system via serial port or recovery mode to disable the overlay

- View serial device information

Using `/dev/ttyUSB0` as an example:

<NewCodeBlock tip="Linux$" type="host">

```bash
ls -l /dev/ttyUSB0
```

</NewCodeBlock>

If the device exists on the system, you will see output similar to:

```text
crw-rw---- 1 root dialout 188, 0 Sep 10 21:24 /dev/ttyUSB0
```

- Add current user to the `dialout` group

<NewCodeBlock tip="Linux$" type="host">

```bash
sudo usermod -a -G dialout $USER
```

</NewCodeBlock>

- Log in again

<NewCodeBlock tip="Linux$" type="host">

```bash
newgrp dialout
```

</NewCodeBlock>

3. Check if the serial device is being used by another program

## Why does Radxa OS use GDM by default instead of SDDM?

Radxa OS uses GDM (GNOME Display Manager) instead of SDDM (Simple Desktop Display Manager) by default for the following reasons:

**SDDM Limitations:**

- SDDM cannot properly start the graphical interface in headless mode when HDMI is not connected
- This prevents users from logging in through remote desktop or VNC

**GDM Advantages:**

- Runs stably in various connection states (including headless mode)
- Provides better compatibility and reliability

If you want to switch back to SDDM, follow these steps:

<NewCodeBlock tip="Linux$" type="host">

```bash
sudo dpkg-reconfigure sddm
```

</NewCodeBlock>

In the configuration interface that appears, select `sddm` as the default display manager, then restart the system for the changes to take effect.

## why my SBC cannot connect Wi-Fi when it is only logged in to the desktop mode?

Because KDE or GNOME desktop environment stores Wi-Fi passwords in the user-specific keyring by default. The keyring will only be unlocked when the user logs in to the graphical interface, which means that the system cannot automatically connect to a protected Wi-Fi network when it is not logged in (such as in headless mode), and SSH cannot be used.
To solve this problem, you can choose one of the following three methods:

- Enable automatic login:
This will allow the system to automatically log in to the specified user, unlocking the keyring, allowing Wi-Fi connection. Use the rsetup tool to enable automatic login.
- Disable keyring encryption:
You can disable keyring encryption by following these steps: KDE Settings -> KDE Wallet -> Disable keyring encryption.
Then forget the Wi-Fi password and reconnect to the Wi-Fi.
This way, the keyring will no longer be encrypted, and the system can access the Wi-Fi password without user login, enabling automatic connection to Wi-Fi networks. Please note that this method reduces system security.
- Use nmtui/nmcli tools to manually add Wi-Fi password:
Use command-line tools nmtui or nmcli to manually configure Wi-Fi network connections and save the password to system-wide configuration files instead of the user's keyring.

<NewCodeBlock tip="Linux$" type="host">

```bash
nmcli connection add type wifi con-name <connection_name> ssid <ssid> password <password>
# or
nmtui
```

</NewCodeBlock>

## Network Connection Automatically Disconnects

You can modify the parameters in the `/usr/share/glib-2.0/schemas/org.gnome.settings-daemon.plugins.power.gschema.xml` file to disable sleep timeout.

<NewCodeBlock tip="radxa@dragon-q6a$" type="device">

```bash
vim /usr/share/glib-2.0/schemas/org.gnome.settings-daemon.plugins.power.gschema.xml
```

</NewCodeBlock>

Modify the `sleep-inactive-ac-timeout` and `sleep-inactive-battery-timeout` parameters in the file to have a default value of `0`, then restart the system for the changes to take effect.

## Why does Q6A reboot immediately when using the hardware encoder?

Before using the hardware encoder, you need to enable the following option in BIOS:

`Hypervisor Settings -> Hypervisor Override in UEFI Setup`

You can enter UEFI Setup by pressing `F2` during boot.

If this option is not enabled, calling the hardware encoder may cause the system to reboot immediately.

After enabling the hardware encoder, the following changes apply:

- The system boots in `EL2` instead of `EL1`, and KVM **can** be used
- `/dev/mtd0` disappears, so you cannot update the SPI firmware directly on the board
**Note:** This issue only affects the DSI overlay for Radxa Display 8 HD. HDMI output and other functions are not affected.
44 changes: 37 additions & 7 deletions i18n/en/docusaurus-plugin-content-docs/current/dragon/q6a/hardware-use/mipi-dsi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,53 @@ sidebar_position: 11

# MIPI DSI Interface

The Dragon Q6A has one 4-lane MIPI DSI interface on board for connecting MIPI displays.
Radxa Dragon Q6A features one 4-lane MIPI DSI interface for connecting MIPI displays.

## Supported Displays

| Model | Size (in inches) | Resolution |
| :--------------------------------------------------------------------------: | :--------------: | :--------: |
| [Radxa Display 10 FHD](https://radxa.com/products/accessories/display-10fhd) | 10.1 | 1200\*1920 |
| [Radxa Display 8 HD](https://radxa.com/products/accessories/display-8hd) | 8 | 800\*1280 |
| Model | Size (inches) | Resolution |
| :--- | :---: | :---: |
| [Radxa Display 10 FHD](https://radxa.com/products/accessories/display-10fhd) | 10.1 | 1200×1920 |
| [Radxa Display 8 HD](https://radxa.com/products/accessories/display-8hd) | 8 | 800×1280 |

## Hardware Connection

Connect the MIPI display to the Dragon Q6A's MIPI DSI interface via an FPC ribbon cable.
Connect the MIPI display to Dragon Q6A's MIPI DSI interface using an FPC ribbon cable.

:::tip Interface Location
Refer to the [Hardware Information](./hardware-info) tutorial to locate the corresponding hardware interface.
:::

## Interface Pin Definition

Refer to the hardware schematic diagram on the [Resource Summary Download](../download) page.
Refer to the hardware schematic in the [Resource Download](../download) page.

## Known Issues and Solutions

### Radxa Display 8 HD Boot Issue

Some users have encountered boot failure issues (blue light stays on then blinks, no display output) after enabling the Radxa Display 8 HD DSI overlay.

**Cause:**
This is a known compatibility issue related to specific kernel versions.

**Affected versions:**
- `linux-image-6.18.2-3-qcom` and earlier versions

**Solution:**
1. Check current kernel version:
```bash
apt policy linux-image-6.18.2-4-qcom
```
2. If `linux-image-6.18.2-4-qcom` is available, update the system:
```bash
sudo apt update
sudo apt upgrade
```
3. Reboot the system

**If the issue persists:**
- Temporarily disable DSI overlay and wait for [linux-qcom](https://github.com/radxa-pkg/linux-qualcomm/releases) to release a fix
- You can access the system via serial port or recovery mode to disable the overlay

**Note:** This issue only affects the DSI overlay for Radxa Display 8 HD. Radxa Display 10 FHD and other functions are not affected.
Loading