From ff341788ec947e1db1d9594c6c2243abfa269f2e Mon Sep 17 00:00:00 2001
From: cheykrym <cheykrym@cheykrym.cheykrym>
Date: Tue, 15 Sep 2026 16:14:49 +0300
Subject: [PATCH] update readme

---
 README.md                  | 223 +++++++++++++++++++++++++++++++----
 docs/auto-start.md         | 230 +++++++++++++++++++++++++++++++++----
 docs/first-system-setup.md | 100 ++++++++++++++++
 3 files changed, 507 insertions(+), 46 deletions(-)
 create mode 100644 docs/first-system-setup.md

diff --git a/README.md b/README.md
index d9ab0c2..6665ea7 100644
--- a/README.md
+++ b/README.md
@@ -1,42 +1,215 @@
-# car_ui
+# Car UI
 
-Интерфейс магнитолы для Raspberry Pi (PySide6), экран 1024x600.
+Интерфейс автомобильной мультимедийной системы для Raspberry Pi 4B с сенсорным дисплеем.
 
-## Требования
+Приложение разработано на Python с использованием PySide6 / Qt 6 и рассчитано на работу как в обычном Desktop Environment во время разработки, так и напрямую через Qt EGLFS / DRM/KMS в production-режиме.
 
-- Python 3.13.5
+## Architecture
 
-## Как запускать
+В production-режиме полноценный Desktop Environment не используется.
 
-Право на запуск:
-
-```bash
-chmod +x setup_venv.sh run_ui.sh build_app.sh
+```text
+Raspberry Pi 4B
+      ↓
+Debian 13 (Trixie)
+      ↓
+systemd
+      ↓
+multi-user.target
+      ↓
+tty1
+      ↓
+car-ui.service
+      ↓
+Qt EGLFS
+      ↓
+DRM/KMS
+      ↓
+Car UI
 ```
 
-Запуск:
+Bluetooth подготавливается отдельным `bt-unblock.service`, который снимает RFKill-блокировку перед запуском Car UI.
 
-```bash
-./setup_venv.sh
-./run_ui.sh
-./build_app.sh
+## Project structure
+
+```text
+car_ui/
+├── assets/             # Ресурсы приложения
+├── audio/              # Работа с аудио
+├── controllers/        # Контроллеры приложения
+├── docs/               # Документация
+├── screens/            # Экраны интерфейса
+├── scripts/            # Build / run / deploy scripts
+├── services/           # Сервисы приложения
+├── system_configs/     # systemd units и системная конфигурация
+├── themes/             # Темы интерфейса
+├── ui/                 # UI-компоненты
+│
+├── car_ui.spec         # Конфигурация PyInstaller
+├── main.py             # Entry point
+├── requirements.txt    # Python-зависимости
+└── README.md
 ```
 
-## Скрипты
+## Quick start
 
-- `setup_venv.sh` — создает виртуальное окружение `.venv` и устанавливает зависимости из `requirements.txt`.
-- `run_ui.sh` — запускает UI локально, выставляя `DISPLAY=:0` и выполняя `main.py`.
-- `build_app.sh` — собирает приложение через PyInstaller в `dist/` (имя `car_ui`).
+### Development
 
-## Конфиг
+Подготовить окружение и собрать проект:
 
-Файл конфигурации UI находится здесь: `~/.config/car_ui/ui.conf`.
+```bash
+./scripts/build.sh
+```
 
-## Файлы-маркеры в корне
+`build.sh` автоматически:
 
-В корне проекта могут находиться специальные файлы-маркеры:
+- создаёт `.venv`, если окружение отсутствует;
+- устанавливает зависимости из `requirements.txt`;
+- собирает приложение через PyInstaller.
 
-- `reset` — сигнал сброса до заводских настроек.
-- `dev_mode_enable` — сигнал включения режима разработчика.
+Для запуска исходного кода:
 
-Если нужен соответствующий режим, создайте пустой файл с нужным именем; удалите файл, чтобы отключить режим.
+```bash
+./scripts/run.sh
+```
+
+Логи прямого запуска сохраняются в:
+
+```text
+debug.log
+```
+
+### Build
+
+Собрать standalone-приложение:
+
+```bash
+./scripts/build.sh
+```
+
+Результат сборки:
+
+```text
+dist/car_ui/
+├── car_ui
+└── _internal/
+```
+
+PyInstaller использует конфигурацию:
+
+```text
+car_ui.spec
+```
+
+### Deploy
+
+Установить готовую сборку в систему:
+
+```bash
+sudo ./scripts/deploy.sh
+```
+
+Приложение устанавливается в:
+
+```text
+/opt/car_ui/
+```
+
+Production systemd service запускает:
+
+```text
+/opt/car_ui/car_ui
+```
+
+## Production and Development modes
+
+Car UI поддерживает два режима работы системы.
+
+### Car mode
+
+Используется для штатной работы магнитолы:
+
+```text
+multi-user.target
+        ↓
+       tty1
+        ↓
+    Qt EGLFS
+        ↓
+      Car UI
+```
+
+Desktop Environment при этом не запускается.
+
+### Development mode
+
+Для разработки используется обычный:
+
+```text
+graphical.target
+        ↓
+Desktop Environment
+        ↓
+scripts/run.sh
+```
+
+Инструкции по настройке и переключению режимов находятся в:
+
+[`docs/auto-start.md`](docs/auto-start.md)
+
+## First system setup
+
+Инструкция по подготовке чистой Debian 13 (Trixie), установке системных зависимостей, сборке и первоначальному развёртыванию:
+
+[`docs/first-system-setup.md`](docs/first-system-setup.md)
+
+## Configuration
+
+Конфигурация UI хранится в:
+
+```text
+~/.config/car_ui/ui.conf
+```
+
+## Marker files
+
+В корне проекта могут использоваться специальные marker-файлы.
+
+### `reset`
+
+Сигнал приложению выполнить сброс до заводских настроек.
+
+Создать:
+
+```bash
+touch reset
+```
+
+Удалить:
+
+```bash
+rm reset
+```
+
+### `dev_mode_enable`
+
+Включает режим разработчика приложения.
+
+Создать:
+
+```bash
+touch dev_mode_enable
+```
+
+Удалить:
+
+```bash
+rm dev_mode_enable
+```
+
+## Documentation
+
+Основная документация проекта находится в `docs/`:
+
+- [`first-system-setup.md`](docs/first-system-setup.md) — подготовка чистой системы;
+- [`auto-start.md`](docs/auto-start.md) — systemd, автоматический запуск и переключение Car / Development mode.
diff --git a/docs/auto-start.md b/docs/auto-start.md
index ed33973..b6cffc7 100644
--- a/docs/auto-start.md
+++ b/docs/auto-start.md
@@ -1,49 +1,237 @@
+# Automatic startup
 
+Настройка автоматического запуска Car UI без Desktop Environment.
 
-# 1. Установить unit
-```bash
-sudo cp system_configs/bt-unblock.service /etc/systemd/system/bt-unblock.service
-sudo cp system_configs/car-ui.service /etc/systemd/system/car-ui.service
+В production-режиме система загружается в `multi-user.target`, после чего
+Car UI запускается через Qt EGLFS/DRM на `tty1`.
+
+Схема запуска:
+
+```text
+Debian
+  ↓
+systemd
+  ↓
+multi-user.target
+  ↓
+tty1
+  ↓
+car-ui.service
+  ↓
+Qt EGLFS
+  ↓
+DRM/KMS
+  ↓
+Car UI
 ```
 
-# 2. Освободить tty1 для Car UI
+## Car mode
+
+### 1. Установить systemd units
+
+Скопировать systemd-сервисы:
+
+```bash
+sudo cp system_configs/car-ui.service /etc/systemd/system/car-ui.service
+sudo cp system_configs/bt-unblock.service /etc/systemd/system/bt-unblock.service
+```
+
+Перечитать конфигурацию systemd:
+
+```bash
+sudo systemctl daemon-reload
+```
+
+### 2. Освободить tty1 для Car UI
+
+Car UI использует `tty1` для прямого доступа Qt EGLFS к DRM/KMS.
+
+Отключить стандартный login prompt на `tty1`:
+
 ```bash
 sudo systemctl disable --now getty@tty1.service
 sudo systemctl mask getty@tty1.service
 ```
 
-# 3. Перечитать units
+### 3. Включить необходимые сервисы
+
+Включить автоматическое снятие RFKill-блокировки Bluetooth:
+
 ```bash
-sudo systemctl daemon-reload
+sudo systemctl enable bt-unblock.service
 ```
 
-# 4. Включить автозапуск Car UI
+Включить автоматический запуск Car UI:
+
+```bash
+sudo systemctl enable car-ui.service
+```
+
+### 4. Отключить Desktop Environment при загрузке
+
+Установить `multi-user.target` как target по умолчанию:
+
+```bash
+sudo systemctl set-default multi-user.target
+```
+
+### 5. Проверить конфигурацию
+
+Проверить target по умолчанию:
+
+```bash
+systemctl get-default
+```
+
+Ожидаемый результат:
+
+```text
+multi-user.target
+```
+
+Проверить сервисы:
+
+```bash
+systemctl is-enabled bt-unblock.service
+systemctl is-enabled car-ui.service
+```
+
+Ожидаемый результат для обоих:
+
+```text
+enabled
+```
+
+Проверить состояние `getty@tty1`:
+
+```bash
+systemctl is-enabled getty@tty1.service
+```
+
+Ожидаемый результат:
+
+```text
+masked
+```
+
+### 6. Перезагрузить систему
+
+```bash
+sudo reboot
+```
+
+После загрузки Car UI должен автоматически запуститься без Desktop Environment.
+
+---
+
+## Development mode
+
+Для разработки можно вернуть обычный Desktop Environment.
+
+### 1. Отключить автоматический запуск Car UI
+
+```bash
+sudo systemctl disable car-ui.service
+```
+
+### 2. Вернуть login prompt на tty1
+
+```bash
+sudo systemctl unmask getty@tty1.service
+sudo systemctl enable getty@tty1.service
+```
+
+### 3. Включить графический режим загрузки
+
+```bash
+sudo systemctl set-default graphical.target
+```
+
+### 4. Перезагрузить систему
+
+```bash
+sudo reboot
+```
+
+После загрузки должен запуститься обычный Desktop Environment.
+
+Car UI в development mode можно запускать напрямую из исходного кода:
+
+```bash
+./scripts/run.sh
+```
+
+---
+
+## Return to Car mode
+
+Для возврата из Development mode в production Car mode:
+
+### 1. Освободить tty1
+
+```bash
+sudo systemctl disable --now getty@tty1.service
+sudo systemctl mask getty@tty1.service
+```
+
+### 2. Включить сервисы
+
 ```bash
 sudo systemctl enable bt-unblock.service
 sudo systemctl enable car-ui.service
 ```
 
-# 5. Загружаться без Desktop
+### 3. Вернуть консольный режим загрузки
+
 ```bash
 sudo systemctl set-default multi-user.target
 ```
 
-# 6. Проверка
-```bash
-systemctl get-default
-systemctl is-enabled car-ui.service
-```
+### 4. Перезагрузить систему
 
-# 7. Перезагрузка
 ```bash
 sudo reboot
 ```
 
-## Включить Desktop
+---
+
+## Диагностика
+
+Проверить состояние Car UI:
+
 ```bash
-sudo systemctl disable car-ui.service
-sudo systemctl unmask getty@tty1.service
-sudo systemctl enable getty@tty1.service
-sudo systemctl set-default graphical.target
-sudo reboot
+systemctl status car-ui.service --no-pager -l
+```
+
+Посмотреть журнал текущей загрузки:
+
+```bash
+journalctl -u car-ui.service -b
+```
+
+Показать последние 100 записей:
+
+```bash
+journalctl -u car-ui.service -b --no-pager -n 100
+```
+
+Проверить Bluetooth:
+
+```bash
+systemctl status bluetooth.service
+systemctl status bt-unblock.service
+rfkill list
+```
+
+Проверить DRM-устройства:
+
+```bash
+ls -l /dev/dri/
+```
+
+Проверить активную виртуальную консоль:
+
+```bash
+fgconsole
+cat /sys/class/tty/tty0/active
 ```
diff --git a/docs/first-system-setup.md b/docs/first-system-setup.md
new file mode 100644
index 0000000..3b08429
--- /dev/null
+++ b/docs/first-system-setup.md
@@ -0,0 +1,100 @@
+# First system setup
+
+Первоначальная настройка Raspberry Pi для запуска Car UI.
+
+Инструкция рассчитана на Debian 13 (Trixie).
+
+## 1. Установить системные зависимости
+
+```bash
+sudo apt update
+
+sudo apt install \
+    python3 \
+    python3-venv \
+    rfkill \
+    bluetooth \
+    bluez \
+    fonts-noto
+```
+
+## 2. Настроить пользователя
+
+Добавить пользователя в группы, необходимые для работы с оборудованием:
+
+```bash
+sudo usermod -aG audio,video,render,input,bluetooth cheykrym
+```
+
+После изменения групп необходимо перелогиниться или перезагрузить систему:
+
+```bash
+sudo reboot
+```
+
+Проверить группы:
+
+```bash
+groups cheykrym
+```
+
+## 3. Проверить Bluetooth вручную
+
+Проверить состояние RFKill:
+
+```bash
+rfkill list
+````
+
+При необходимости вручную снять блокировку:
+
+```bash
+sudo rfkill unblock bluetooth
+```
+
+Проверить Bluetooth service:
+
+```bash
+systemctl status bluetooth.service
+```
+
+При автоматическом запуске снятие RFKill-блокировки выполняется
+`bt-unblock.service`.
+
+## 4. Подготовить проект
+
+Перейти в директорию проекта и выполнить:
+
+```bash
+./scripts/build.sh
+```
+
+Скрипт автоматически:
+
+* создаст `.venv`, если его ещё нет;
+* установит Python-зависимости из `requirements.txt`;
+* соберёт приложение через PyInstaller.
+
+Готовая сборка появится в:
+
+```text
+dist/car_ui/
+```
+
+## 5. Установить приложение
+
+```bash
+sudo ./scripts/deploy.sh
+```
+
+Приложение будет установлено в:
+
+```text
+/opt/car_ui/
+```
+
+## 6. Настроить автоматический запуск
+
+После установки приложения выполнить настройку systemd согласно:
+
+[`docs/auto-start.md`](auto-start.md)