Button/docs/display-blank-investigation.md

# Тёмный экран при горящей подсветке: расследование

Дата: 2026-11-11. Экземпляр: возврат с объекта (жалоба: «подсветка горит, картинки нет, лечится передёргиванием питания»), питание PoE.
Плата: `Rockchip RK3566 EVB2 LP4X V10 Board`, ядро 5.10.209 (сборка 2025-12-02), Debian 11. Панель MIPI-DSI 480×480, драйвер `simple-panel-dsi`, контроллер панели по init-последовательности ST7701S (`FF 77 01 00 00 10`).

## Коротко

1. **Сбой воспроизведён без PoE.** Достаточно (а) тёплой перезагрузки или (б) короткого импульса на линии сброса панели: панель гаснет, подсветка горит, SoC продолжает выводить кадры, ядро не пишет ни одной ошибки.
2. **Со стороны SoC сбой не виден.** Конвейер VOP2 → DSI активен, режим 480x480p60, кадр выводится, подсветка включена. DSI работает в video mode без подтверждений от панели, поэтому потерю инициализации панели ядро обнаружить не может.
3. **Панель после загрузки остаётся без управления по питанию.** Ядро принимает дисплей, инициализированный U-Boot (передача логотипа), и не выполняет последовательность включения панели. Линии питания панели остаются **входами без драйвера**:

   | GPIO | назначение (DT) | после загрузки | после повторной инициализации драйвером |
   |---|---|---|---|
   | gpio-16 (GPIO0_C0) | `reset-gpios`, активный низкий | out, high | out, high |
   | gpio-17 (GPIO0_C1) | `powers-gpios` | **in, low** | out, high |
   | gpio-18 (GPIO0_C2) | `enable-gpios` | out, high | out, high |
   | gpio-20 (GPIO0_C4) | `avee-gpios` | **in, high** | out, high |

   После U-Boot `powers` — вход с низким уровнем, а панель при этом работает. Значит, эта линия, скорее всего, питание панели не отключает. `avee` — вход с высоким уровнем при внутренней подтяжке вниз (`GPIO0_C4_d`), то есть её держит в высоком уровне что-то на плате. Неуправляемая линия `avee` может быть уязвима к помехам: импульсная помеха или просадка по PoE снимет питание или сбросит контроллер панели при живом SoC. Это гипотеза, не доказано. Совпадает с наблюдениями на объектах: ядро живо, тач работает, картинки нет.
4. **Конфликт выводов в device tree.** В дереве описана вторая подсветка `backlight1` на контроллере `pwm@fe6e0010` (PWM5). Её настройка выводов `pwm5-pins` — это **GPIO0_C4, та же нога, что `avee` панели**. Сейчас ногу держит панель (функция GPIO). PWM5 не включён, его настройка выводов не применена (`current state: none`), скважность 0. Если `backlight1` активируют (запись в `/sys/class/backlight/backlight1`, иной порядок загрузки драйверов), нога может переключиться на ШИМ со скважностью 0. Тогда `avee` упадёт в ноль: картинки нет, подсветка (PWM4, GPIO0_C3) горит. Срабатывание не проверено, но сама ошибка в дереве очевидна. Наше ПО `backlight1` не трогает (`bt-brightness` работает с `backlight`).

   Распределение выводов на работающем устройстве (`/sys/kernel/debug/pinctrl/pinctrl-rockchip-pinctrl/pinmux-pins`):

   | вывод | функция | владелец |
   |---|---|---|
   | GPIO0_C0 | GPIO | панель, `reset` |
   | GPIO0_C1 | GPIO | панель, `powers` |
   | GPIO0_C2 | GPIO | панель, `enable` |
   | GPIO0_C3 | PWM4 | `backlight` (рабочая подсветка) |
   | GPIO0_C4 | GPIO | панель, `avee`; **на неё же указывает `pwm5-pins` для `backlight1`** |

   UART0 (альтернатива для C0/C1) в дереве выключен. Видеовыход — только DSI-1 (480×480p60, Video Port1). HDMI описан, но выключен.
5. **Лечится без перезагрузки:** `blank` / `unblank` дисплея (`/sys/class/graphics/fb0/blank`: 4, затем 0) при остановленном UI. Драйвер панели выполняет полную последовательность: питание, сброс, init-команды. После этого все четыре линии становятся управляемыми выходами.

## Как воспроизвести

Все команды выполняются от root на устройстве.

**А. Тёплая перезагрузка.** `systemctl reboot` (питание не снимается). После загрузки экран остался тёмным при горящей подсветке. Повторяемость уточняется (см. ниже).

**Б. Импульс сброса панели в обход драйвера** (имитация помехи на линии сброса):
```sh
busybox devmem 0xfdd60004 32 0x00010000   # GPIO0 SWPORT_DR_H: бит 0 (GPIO0_C0, reset) = 0, маска только на этот бит
sleep 0.2
busybox devmem 0xfdd60004 32 0x00010001   # вернуть 1
```
Результат: картинка пропала, подсветка горит, в `dmesg` ни одной строки.

**Проверка, что SoC выводит кадры:**
`cat /sys/kernel/debug/dri/0/summary`. В нём видно `Video Port1: ACTIVE`, `DSI-1`, `480x480p60`, `Smart0-win0: ACTIVE`.

**Восстановление** (обе ситуации А и Б, проверено визуально):
```sh
systemctl stop buttontask
echo 4 > /sys/class/graphics/fb0/blank
echo 0 > /sys/class/graphics/fb0/blank
systemctl start buttontask
```
(В прошивке это делает `bt-displaywatch recover` или жест «10 с в нижнем левом углу».)

## Что просить у производителя платы / BSP

1. В device tree и U-Boot: линии `powers-gpios` (GPIO0_C1) и `avee-gpios` (GPIO0_C4) должны с момента включения быть **выходами** в активном уровне. Не оставлять их входами после передачи дисплея от U-Boot ядру. Подтянуть их резисторами на плате, если это предусмотрено схемой.
2. Объяснить, почему после тёплой перезагрузки (питание панели не снималось) панель не инициализируется заново. Вероятно, U-Boot не выполняет сброс и init-последовательность панели, если она уже была включена, а ядро не делает этого из-за передачи логотипа.
3. Проверить помехоустойчивость линии сброса панели (GPIO0_C0) и питания панели при работе от PoE: просадки и импульсные помехи при включении других PoE-нагрузок.
4. Убрать конфликт в device tree: `backlight1` (PWM5, `pwm5-pins` = GPIO0_C4) указывает на ногу `avee-gpios` панели. Отключить `pwm@fe6e0010` и `backlight1`, если вторая подсветка не используется.
5. По возможности: способ из ядра узнать, что панель жива. Например, периодическое DCS-чтение `get_power_mode` (0x0A), чтобы сбой обнаруживался автоматически.

## Что сделано в нашем ПО (обход)

- `bt-displaywatch` переинициализирует панель (blank/unblank) по ошибкам DRM/DSI в ядре, по пропаданию Ethernet-линка (признак просадки PoE), по запросу (жест, CLI). При повторяющихся сбоях он перезагружает устройство.
- Жест для персонала: удерживать нижний левый угол экрана 10 с.
- При каждой загрузке, до запуска UI, `bt-displaywatch` выполняет одну такую переинициализацию. Юнит запускается `Before=buttontask.service`, функция `boot_takeover`. Драйвер берёт линии питания панели под управление, и закрывается тёмный экран после тёплой перезагрузки. Проверено на возвращённом экземпляре: после загрузки `powers`/`avee` стали `out hi`, UI стартует после переинициализации (~0,5 с чёрного экрана до UI).
- Раз в сутки ночью (01:30 UTC = 04:30 МСК, настраивается через `DISPLAYWATCH_DAILY_UTC`) выполняется профилактическая переинициализация: экран моргает примерно на 6 с, приложение перезапускается. Тихий сбой панели (без ошибок ядра и без падения линка) со стороны SoC не обнаружить, поэтому так он длится не дольше суток. Без синхронизированного времени переинициализация выполняется раз в 24 часа аптайма.
- В журнале инцидентов (`/var/log/buttontask/display-incidents.log`) при каждом старте записывается `COLD boot` (питание пропадало) или `WARM boot`, а также как закончилась предыдущая загрузка.
- Каждая строка журнала содержит аптайм и температуру SoC: `2026-11-11 13:03:16 up  44433s  52C …`.

## Другие возможные причины того же симптома

Симптом «подсветка горит, картинки нет, ядро живо» дают и другие причины. Воспроизведённый механизм — самый вероятный, но для объекта не доказан.

| # | причина | признаки | что помогает |
|---|---|---|---|
| 1 | Статика (ESD) при касании: контроллер панели сбрасывается или «зависает» | сбои зимой, при сухом воздухе; кнопку постоянно трогают | переинициализация |
| 2 | Просадка питания панели (PoE, стабилизатор на плате) | совпадения с отключением линка в журнале | переинициализация |
| 3 | Сбой DSI или видеоконтроллера SoC | ошибки DRM/DSI в журнале ядра | переинициализация (срабатывает автоматически) |
| 4 | Приложение рисует чёрное (падение Qt, зависание GPU) | `ui restarted` / `ui frozen` в журнале | перезапуск приложения (вотчдоги) |
| 5 | Шлейф или разъём панели (окисление, вибрация) | помогает нажать на корпус; со временем чаще | ремонт; переинициализация не поможет |
| 6 | Перегрев панели: жидкий кристалл выше ~70–80 °C перестаёт работать | кнопка на солнце, за стеклом, у батареи; высокая температура в журнале | проходит сам после остывания |
| 7 | Деградация панели или её драйвера | отказы всё чаще, затем насовсем | замена |

**Как различить на объекте:**

| что вернуло картинку | вероятная причина |
|---|---|
| жест в углу или автоматическая переинициализация | 1, 2, 3, воспроизведённый механизм |
| перезапуск приложения | 4 |
| только передёргивание питания | 5, 7 или неполная переинициализация |
| экран вернулся сам, когда кнопка остыла | 6 |

Журнал инцидентов фиксирует жест, автоматические переинициализации и температуру. Помогла ли переинициализация, видит только человек у экрана. Персонал стоит попросить отмечать это при жалобе.

## Прочие наблюдения

- Сетевая нагрузка не влияет: 5 минут UDP 80 Мбит/с (2,1 млн пакетов). Ошибок на `eth0` 0, нагрузка CPU < 1, перезагрузок нет.
- По часам rk809 (без батарейки) видно, пропадало ли питание перед загрузкой. Ядро пишет `rk808-rtc: setting system clock to …`: значение `2017-08-04T09:00:0x` означает, что питание пропадало, реальное время означает тёплый перезапуск. Все загрузки этого экземпляра в журнале начинались после пропадания питания.
- `kernel.panic = 0`: при панике ядра плата зависает, а не перезагружается (на прошивке без аппаратного вотчдога).

## Объяснение простыми словами

Внутри кнопки два «работника»: **компьютер** (плата) и **экран**.

Компьютер рисует картинку и всё время отправляет её на экран по проводу, как телевизионный сигнал. Экран эту картинку показывает. Но перед началом работы экран нужно **«разбудить»**: подать на него питание в правильном порядке и проговорить ему набор команд «проснись, вот твои настройки».

**Что идёт не так.** При включении экран будит загрузчик платы. После этого основная система не берёт экран под свой контроль: провода, которые держат питание экрана, остаются «брошенными», их никто не держит. Если в сети питания PoE случается короткий скачок или помеха, экран от этого «засыпает» или сбрасывается и забывает свои настройки. Компьютер при этом ничего не замечает: он продолжает отправлять картинку, а ответа от экрана не ждёт. Поэтому получается так:

- подсветка горит (она питается отдельно);
- картинки нет (экран «спит»);
- кнопка живая, тач работает, но ничего не видно;
- помогает только выдернуть и вставить питание: тогда всё будится заново.

**Почему это не наша программа.** Мы повторили сбой на возвращённой кнопке без всякого PoE: достаточно одного короткого импульса на проводе сброса экрана, и экран гаснет, а система не видит ни одной ошибки. Иногда то же самое происходит и после обычной перезагрузки. Это особенность платы и её начальной прошивки (U-Boot и device tree от производителя платы), а не приложения.

**Что мы сделали.**
- При каждом включении наша программа сразу «будит» экран сама и забирает его провода под контроль, чтобы они больше не болтались.
- Если в сети или в системе случился сбой, похожий на причину, экран будится заново автоматически.
- Раз в сутки ночью экран будится профилактически, на несколько секунд.
- У персонала есть «кнопка спасения»: подержать палец 10 секунд в нижнем левом углу экрана.

**Что должен сделать производитель платы.** Исправить начальную прошивку, чтобы провода питания экрана с самого включения были под управлением. Убрать из настроек платы ошибку, из-за которой один из этих проводов одновременно назначен и экрану, и второй, неиспользуемой подсветке. Проверить, насколько плата и экран устойчивы к помехам по питанию PoE.