BLE Controller - Полная информация о проекте

Основная информация

Название: BLE Controller Версия: 1.0.0 Автор: Alash Electronics Лицензия: MIT Репозиторий: https://github.com/Alash-electronics/bluetoothWebApp Живая демо: https://alash-electronics.github.io/bluetoothWebApp/

Описание проекта

Универсальное веб-приложение для управления Bluetooth устройствами через браузер. Поддерживает HC-06, HC-05, HM-10, ESP32 и другие BLE/Classic Bluetooth модули. Приложение предоставляет несколько режимов управления: терминал, управление RC машинами, джойстик и умный дом.

Поддерживаемые браузеры

✅ Поддерживаются:

• Chrome 56+ (Desktop & Android)

• Edge 79+ (Desktop)

• Opera 43+ (Desktop & Android)

❌ НЕ поддерживаются:

• iOS (iPhone, iPad, iPod) - Apple не поддерживает Web Bluetooth API

• Safari (все платформы) - не поддерживает Web Bluetooth API

• Firefox - не поддерживает Web Bluetooth API

Причина: Web Bluetooth API не реализован в этих браузерах по соображениям безопасности или политики производителя.

Поддерживаемое оборудование

Bluetooth модули:

• HM-10 - BLE 4.0 (рекомендуется для низкого энергопотребления)

• HC-06 - Classic Bluetooth 2.0 SPP

• HC-05 - Classic Bluetooth 2.0 master/slave

• ESP32 - встроенный BLE и Classic Bluetooth

• Arduino BLE модули - BLE Nano, Arduino Nano 33 BLE и т.д.

• Любые UART-over-Bluetooth модули

Микроконтроллеры:

• Arduino Uno, Nano, Mega, Leonardo

• ESP32, ESP8266

• STM32, Raspberry Pi Pico

• Любая плата с поддержкой UART/Serial

Требования по питанию:

• HC-05/HC-06: 3.6V-6V (5V tolerant)

• HM-10: 3.3V (использовать делитель напряжения на 5V платах)

• ESP32: 3.3V

Технологический стек

• Frontend: React 19 с TypeScript

• Build Tool: Vite 7

• Styling: Tailwind CSS 3

• Bluetooth: Web Bluetooth API

• State Management: Singleton services с React hooks

• Storage: Browser localStorage

• Deployment: GitHub Pages

Структура проекта

bluetoothWebApp/
├── README.md                    # Главная документация
├── ABOUT.md                     # Описание проекта
├── LICENSE                      # MIT лицензия
├── CONTRIBUTING.md              # Руководство для контрибьюторов
├── PROJECT_INFO.md              # Этот файл
├── .gitignore                   # Игнорируемые файлы
├── .github-about.txt            # Текст для GitHub About
└── ble-controller/              # Основное приложение
    ├── package.json             # Зависимости и скрипты
    ├── vite.config.ts           # Конфигурация Vite (base: /bluetoothWebApp/)
    ├── tsconfig.json            # Конфигурация TypeScript
    ├── tailwind.config.js       # Конфигурация Tailwind CSS
    ├── CLAUDE.md                # Архитектурная документация
    ├── index.html               # HTML entry point
    ├── public/
    │   ├── logo.png             # Логотип приложения (1000x1000)
    │   └── vite.svg             # Favicon
    ├── src/
    │   ├── main.tsx             # Entry point с ErrorBoundary
    │   ├── App.tsx              # Root компонент с роутингом
    │   ├── index.css            # Глобальные стили
    │   ├── components/          # React UI компоненты
    │   │   ├── SplashScreen.tsx          # Экран загрузки (2 сек)
    │   │   ├── DeviceSelection.tsx       # Выбор типа устройства
    │   │   ├── ControlPanel.tsx          # RC car геймпад интерфейс
    │   │   ├── JoystickPanel.tsx         # PS4-стиль джойстик
    │   │   ├── TerminalPanel.tsx         # Серийный терминал
    │   │   ├── SmartHomePanel.tsx        # Выбор комнаты
    │   │   ├── SmartHomeRoomControl.tsx  # Управление комнатой
    │   │   ├── SettingsPanel.tsx         # Модальные настройки
    │   │   ├── UnsupportedBrowser.tsx    # Сообщение для iOS/Safari
    │   │   ├── ErrorBoundary.tsx         # Отлов ошибок React
    │   │   ├── ConnectionPanel.tsx       # Legacy компонент
    │   │   └── DataPanel.tsx             # Legacy компонент
    │   ├── services/            # Бизнес-логика (singletons)
    │   │   ├── bluetoothService.ts       # Core BLE коммуникация
    │   │   ├── appSettings.ts            # Настройки приложения
    │   │   ├── localization.ts           # Мультиязычность (ru/en/kk)
    │   │   ├── controlPanelSettings.ts   # Настройки кнопок геймпада
    │   │   ├── buttonSettings.ts         # Legacy настройки
    │   │   ├── macroSettings.ts          # Макросы терминала
    │   │   ├── smartHomeSettings.ts      # Настройки умного дома
    │   │   └── roomSettings.ts           # Настройки комнат
    │   └── hooks/               # Custom React hooks
    │       └── useFullscreen.ts          # Fullscreen API hook
    └── arduino-examples/        # Примеры Arduino sketches
        ├── README.md            # Инструкции по подключению
        ├── terminal_basic/      # Эхо-пример
        ├── rc_car_control/      # Управление моторами
        └── smart_home_basic/    # Управление реле/LED

Команды разработки

ВАЖНО: Все команды запускать из директории ble-controller/

# Навигация в директорию проекта
cd bluetoothWebApp/ble-controller

# Установка зависимостей
npm install

# Запуск dev сервера с HTTPS (требуется для Web Bluetooth API)
npm run dev
# Открыть: https://localhost:5173/

# Сборка production версии
npm run build

# Проверка кода (ESLint)
npm run lint

# Просмотр production build локально
npm run preview

# Деплой на GitHub Pages
npm run deploy

Архитектура приложения

Singleton Service Pattern

Приложение использует паттерн singleton services с React hooks:

1. Services (singleton классы) управляют состоянием и бизнес-логикой

2. Components подписываются на обновления через callbacks

3. Settings автоматически сохраняются в localStorage

Bluetooth Service

Файл: src/services/bluetoothService.ts

UUIDs:

• Service: 0000ffe0-0000-1000-8000-00805f9b34fb

• Characteristic: 0000ffe1-0000-1000-8000-00805f9b34fb

Connection States:

• 'disconnected' - не подключено

• 'connecting' - подключение в процессе

• 'connected' - подключено

Основные методы:

• connect() - подключение к BLE устройству

• disconnect() - отключение

• sendData(data: string) - отправка данных

• onDataReceived(callback) - подписка на получение данных

• onConnectionStatusChange(callback) - подписка на изменение статуса

View Routing System

ViewMode типы:

type ViewMode = 'selection' | 'control' | 'joystick' | 'terminal' | 'smartHome' | 'smartHomeRoom';

Навигация:

1. SplashScreen (2 сек) → DeviceSelection

2. Выбор типа устройства → соответствующий view

3. Disconnect → автоматический возврат в DeviceSelection

Режимы ориентации

TerminalPanel:

• Работает только в portrait режиме

• Блокирует landscape на мобильных (<1024px)

• Показывает оверлей с предложением повернуть устройство

ControlPanel & JoystickPanel:

• Работают только в landscape режиме

• Блокируют portrait на мобильных (<1024px)

• Показывают оверлей с предложением повернуть устройство

Порог: 1024px (не 640px) - iPhone 14 Pro Max = 932px

Кнопки и элементы управления

Системные кнопки (присутствуют во всех панелях)

1. Кнопка GitHub (левый верхний угол)

• Внешний вид: Логотип GitHub (Octocat)

• Расположение: Левый верхний угол всех панелей

• Функция: Открывает репозиторий проекта на GitHub в новой вкладке

• URL: https://github.com/Alash-electronics/bluetoothWebApp

• Вибрация: 30ms при клике

2. Кнопка Fullscreen (правый верхний угол)

• Внешний вид: Иконка «развернуть» (4 стрелки наружу)

• Расположение: Правый верхний угол панелей

• Функция: Переключает полноэкранный режим

• Поведение:

  • На Desktop/Android: показывается и работает

  • На iOS: автоматически скрывается (Fullscreen API не поддерживается)

• Альтернатива для iOS: «Add to Home Screen» через Safari

• Вибрация: 30ms при клике

3. Кнопка Settings (иконка шестеренки)

• Внешний вид: Иконка шестеренки ⚙️

• Расположение: Рядом с кнопкой Fullscreen

• Функция: Открывает панель настроек (SettingsPanel)

• Содержимое настроек зависит от режима:

  • Control Mode: настройки кнопок геймпада

  • Terminal Mode: настройки макросов

  • Smart Home Mode: настройки устройств, сенсоров, комнат

  • General Settings: язык, тема, вибрация

• Вибрация: 30ms при клике

4. Кнопка Language (переключатель языка)

• Внешний вид: Текст языка («Русский», «English», «Қазақша»)

• Расположение: Правый верхний угол, рядом с шестеренкой

• Функция: Циклически переключает языки: RU → EN → KK → RU

• Языки:

  • 🇷🇺 Русский (ru)

  • 🇬🇧 English (en)

  • 🇰🇿 Қазақша (kk)

• Сохранение: Автоматически в localStorage

• Вибрация: 30ms при клике

5. Кнопка Bluetooth Status (статус подключения)

• Внешний вид:

  • 🔴 Красная точка + «Отключен» (disconnected)

  • 🟡 Желтая точка + «Подключение…» (connecting) с пульсацией

  • 🟢 Зеленая точка + «Подключен» (connected)

• Расположение: Центр заголовка панели

• Функция: Кликабельна - показывает диалог подключения/отключения

  • Если отключено: запускает процесс подключения

  • Если подключено: показывает confirm диалог для отключения

• Вибрация: 30ms при клике

6. Кнопка Back/Disconnect (назад/отключиться)

• Внешний вид: Иконка стрелки влево ← или текст «Назад»/»Отключиться»

• Расположение: Левый верхний угол или в заголовке

• Функция:

  • Отключает Bluetooth

  • Возвращает на экран DeviceSelection

• Вибрация: 30ms при клике

---

DeviceSelection Panel (Экран выбора устройства)

Кнопки выбора типа устройства (4 большие карточки):

1. RC Car (Машина)

• Внешний вид: Большая карточка с иконкой 🚗

• Текст: «RC Car» / «RC Машина»

• Описание: «Геймпад управление»

• Функция: Переключает на ControlPanel (геймпад режим)

• Команда: setViewMode('control')

• Вибрация: 30ms

2. Terminal (Терминал)

• Внешний вид: Большая карточка с иконкой 💻

• Текст: «Terminal» / «Терминал»

• Описание: «Серийный терминал с макросами»

• Функция: Переключает на TerminalPanel

• Команда: setViewMode('terminal')

• Вибрация: 30ms

3. Joystick (Джойстик)

• Внешний вид: Большая карточка с иконкой 🎮

• Текст: «Joystick» / «Джойстик»

• Описание: «Двойной джойстик PS4-стиль»

• Функция: Переключает на JoystickPanel

• Команда: setViewMode('joystick')

• Вибрация: 30ms

4. Smart Home (Умный дом)

• Внешний вид: Большая карточка с иконкой 🏠

• Текст: «Smart Home» / «Умный дом»

• Описание: «Управление комнатами и устройствами»

• Функция: Переключает на SmartHomePanel

• Команда: setViewMode('smartHome')

• Вибрация: 30ms

Особенности карточек:

• Градиентные цвета (синий, фиолетовый, зеленый, оранжевый)

• Hover эффект: трансформация и тень

• Responsive: уменьшаются на мобильных устройствах

• Layout: 2x2 сетка на desktop, вертикальная на mobile

---

ControlPanel (RC Car - Геймпад режим)

Ориентация: Только landscape (альбомная)

Основные кнопки управления (8 кнопок):

Левая группа (направления):

1. Forward (Вперед) - Кнопка ▲

   • Расположение: Верхняя кнопка в левом D-pad

   • Цвет: Синий градиент

   • Команда по умолчанию: 'F'

   • Метод отправки: sendData('F')

   • Настраивается: Да (через Settings)

   • Вибрация: 30ms

2. Backward (Назад) - Кнопка ▼

   • Расположение: Нижняя кнопка в левом D-pad

   • Цвет: Синий градиент

   • Команда по умолчанию: 'B'

   • Метод отправки: sendData('B')

   • Настраивается: Да

   • Вибрация: 30ms

3. Left (Влево) - Кнопка ◀

   • Расположение: Левая кнопка в левом D-pad

   • Цвет: Синий градиент

   • Команда по умолчанию: 'L'

   • Метод отправки: sendData('L')

   • Настраивается: Да

   • Вибрация: 30ms

4. Right (Вправо) - Кнопка ▶

   • Расположение: Правая кнопка в левом D-pad

   • Цвет: Синий градиент

   • Команда по умолчанию: 'R'

   • Метод отправки: sendData('R')

   • Настраивается: Да

   • Вибрация: 30ms

Правая группа (действия):

5. Button X - Кнопка X

   • Расположение: Левая кнопка в правом кластере

   • Цвет: Синий

   • Команда по умолчанию: 'X'

   • Метод отправки: sendData('X')

   • Настраивается: Да

   • Вибрация: 30ms

6. Button Y - Кнопка Y

   • Расположение: Верхняя кнопка в правом кластере

   • Цвет: Желтый

   • Команда по умолчанию: 'Y'

   • Метод отправки: sendData('Y')

   • Настраивается: Да

   • Вибрация: 30ms

7. Button A - Кнопка A

   • Расположение: Нижняя кнопка в правом кластере

   • Цвет: Зеленый

   • Команда по умолчанию: 'A'

   • Метод отправки: sendData('A')

   • Настраивается: Да

   • Вибрация: 30ms

8. Button B - Кнопка B

   • Расположение: Правая кнопка в правом кластере

   • Цвет: Красный

   • Команда по умолчанию: 'B'

   • Метод отправки: sendData('B')

   • Настраивается: Да

   • Вибрация: 30ms

Центральная кнопка:

9. Stop (Стоп) - Кнопка ■

   • Расположение: Центр экрана между D-pad и кнопками

   • Цвет: Красный

   • Размер: Больше остальных кнопок

   • Команда по умолчанию: 'S'

   • Метод отправки: sendData('S')

   • Функция: Аварийная остановка/сброс

   • Настраивается: Да

   • Вибрация: 50ms (длиннее для важности)

Настройка кнопок:

• Через Settings → Control Panel Settings

• Можно изменить команду для каждой кнопки

• Сохраняется в controlPanelSettings service

• localStorage ключ: controlPanelSettings

---

JoystickPanel (Двойной джойстик)

Ориентация: Только landscape (альбомная)

Джойстики (2 виртуальных джойстика):

1. Левый джойстик

• Расположение: Левая половина экрана

• Внешний вид: Круглая область с движущимся кружком

• Цвет: Синий градиент

• Функция: Управление движением (обычно моторы)

• Данные передачи:

  • Ось X: -100 до +100 (влево-вправо)

  • Ось Y: -100 до +100 (вниз-вверх)

  • Формат: X:[x],Y:[y] (например: X:50,Y:-30)

• Частота отправки: ~100ms (10 раз в секунду)

• Reset: Автоматически возвращается в центр при отпускании

• Вибрация: Нет (для плавности)

2. Правый джойстик

• Расположение: Правая половина экрана

• Внешний вид: Круглая область с движущимся кружком

• Цвет: Зеленый градиент

• Функция: Дополнительное управление (например, камера/манипулятор)

• Данные передачи:

  • Ось X2: -100 до +100

  • Ось Y2: -100 до +100

  • Формат: X2:[x],Y2:[y]

• Частота отправки: ~100ms

• Reset: Автоматически возвращается в центр

• Вибрация: Нет

Поведение:

• Touch/Mouse tracking: Перемещение следует за пальцем/мышью

• Dead zone: Центральная зона ~10% игнорируется

• Boundary: Движение ограничено кругом джойстика

• Visual feedback: Круг следует за позицией, линия показывает направление

Протокол данных:

// При движении обоих джойстиков
X:45,Y:78,X2:-23,Y2:56

// Только левый
X:45,Y:78,X2:0,Y2:0

// Только правый
X:0,Y:0,X2:-23,Y2:56

---

TerminalPanel (Терминал)

Ориентация: Только portrait (портретная)

1. Поле ввода (Terminal Input)

• Расположение: Верхняя часть экрана

• Внешний вид: Текстовое поле на темном фоне

• Функция: Ввод текстовых команд для отправки

• Placeholder: «Введите команду…»

• Поведение:

  • Enter отправляет команду

  • Очищается после отправки

  • История команд не сохраняется (TODO)

2. Кнопка Send (Отправить)

• Расположение: Справа от поля ввода

• Цвет: Синий

• Функция: Отправляет текст из input поля

• Метод: sendData(inputText)

• Вибрация: 30ms

3. Область вывода (Terminal Output)

• Расположение: Центральная часть экрана

• Внешний вид: Прокручиваемая область с монопространным шрифтом

• Функция: Отображает полученные данные от устройства

• Формат:

  • Каждое сообщение на новой строке

  • Timestamp опционально

  • Автоскролл вниз

• Максимум строк: ~1000 (затем старые удаляются)

• Кнопка Clear: Очистить весь вывод

4. Макро-кнопки (12 кнопок)

Расположение: Нижняя часть экрана, сетка 4x3

Кнопки по умолчанию:

Строка 1:

• M1: Команда '1', Название «Макрос 1»

• M2: Команда '2', Название «Макрос 2»

• M3: Команда '3', Название «Макрос 3»

• M4: Команда '4', Название «Макрос 4»

Строка 2:

• M5: Команда '5', Название «Макрос 5»

• M6: Команда '6', Название «Макрос 6»

• M7: Команда '7', Название «Макрос 7»

• M8: Команда '8', Название «Макрос 8»

Строка 3:

• M9: Команда '9', Название «Макрос 9»

• M10: Команда '0', Название «Макрос 10»

• M11: Команда 'A', Название «Макрос 11»

• M12: Команда 'B', Название «Макрос 12»

Свойства макро-кнопок:

• Цвет: Случайные пастельные цвета (генерируются автоматически)

• Настраивается: Полностью через Settings

  • Название кнопки (отображаемый текст)

  • Команда (отправляемая строка)

• Метод: sendData(command)

• Вибрация: 30ms

• Сохранение: localStorage через macroSettings service

Настройка макросов:

• Settings → Terminal Settings → Macro Buttons

• Поля: Label (название), Command (команда)

• Автосохранение при изменении

---

SmartHomePanel (Выбор комнаты)

Ориентация: Любая

Кнопки комнат (до 6 комнат)

Комнаты по умолчанию:

1. Living Room (Гостиная)

   • Иконка: 🛋️

   • Цвет: Синий градиент

   • ID: 'living-room'

   • Функция: Открывает SmartHomeRoomControl для этой комнаты

2. Bedroom (Спальня)

   • Иконка: 🛏️

   • Цвет: Фиолетовый градиент

   • ID: 'bedroom'

   • Функция: Открывает SmartHomeRoomControl

3. Kitchen (Кухня)

   • Иконка: 🍳

   • Цвет: Оранжевый градиент

   • ID: 'kitchen'

   • Функция: Открывает SmartHomeRoomControl

4. Bathroom (Ванная)

   • Иконка: 🚿

   • Цвет: Голубой градиент

   • ID: 'bathroom'

   • Функция: Открывает SmartHomeRoomControl

5. Garden (Сад)

   • Иконка: 🌱

   • Цвор: Зеленый градиент

   • ID: 'garden'

   • Функция: Открывает SmartHomeRoomControl

6. Garage (Гараж)

   • Иконка: 🚗

   • Цвет: Серый градиент

   • ID: 'garage'

   • Функция: Открывает SmartHomeRoomControl

Свойства кнопок комнат:

• Размер: Большие карточки (как DeviceSelection)

• Layout: Сетка 2x3 или вертикальная на mobile

• Настраивается: Полностью через Settings

  • Название комнаты

  • Иконка (emoji picker)

  • Добавление/удаление комнат

• Максимум: 6 комнат

• Вибрация: 30ms

• Сохранение: roomSettings service

Кнопка Add Room (+):

• Показывается если комнат < 6

• Открывает диалог создания комнаты

• Поля: Name, Icon (emoji)

---

SmartHomeRoomControl (Управление комнатой)

Ориентация: Любая

1. Секция Devices (Устройства) - 6 устройств

Устройства по умолчанию:

LED (Лампа)

• Иконка: 💡

• Состояние: ON/OFF (toggle)

• Команда ON: 'L'

• Команда OFF: 'l'

• Цвет ON: Желтый

• Цвет OFF: Серый

• Настраивается: Название, команды ON/OFF

Window (Окно/Штора)

• Иконка: 🪟

• Состояние: ON (открыто) / OFF (закрыто)

• Команда ON: 'W'

• Команда OFF: 'w'

• Цвет ON: Голубой

• Цвет OFF: Серый

Music (Музыка/Аудио)

• Иконка: 🎵

• Состояние: ON/OFF

• Команда ON: 'M'

• Команда OFF: 'm'

• Цвет ON: Розовый

• Цвет OFF: Серый

Door (Дверь/Замок)

• Иконка: 🚪

• Состояние: ON (открыто) / OFF (закрыто)

• Команда ON: 'D'

• Команда OFF: 'd'

• Цвет ON: Зеленый

• Цвет OFF: Серый

Fan (Вентилятор)

• Иконка: 🌀

• Состояние: ON/OFF

• Команда ON: 'N'

• Команда OFF: 'n'

• Цвет ON: Голубой (rotating animation)

• Цвет OFF: Серый

AC (Кондиционер)

• Иконка: ❄️

• Состояние: ON/OFF

• Команда ON: 'K'

• Команда OFF: 'k'

• Цвет ON: Синий

• Цвет OFF: Серый

• Особенность: Открывает отдельную панель управления AC

Свойства кнопок устройств:

• Layout: Сетка 3x2 (или 2x3 на portrait)

• Размер: Средние карточки

• Toggle: Один клик переключает состояние

• Visual feedback: Анимация и изменение цвета

• Вибрация: 30ms

• Настройка: Settings → Smart Home → Devices

  • Label (название)

  • On Command (1 символ)

  • Off Command (1 символ)

2. Секция Sensors (Сенсоры) - 3 сенсора

Сенсоры по умолчанию:

Motion (Датчик движения)

• Иконка: 🚶

• Состояние: Read-only (только чтение)

• Сообщение ON: 'motion' (настраивается)

• Сообщение OFF: 'no_motion'

• Индикатор ON: Красный (тревога)

• Индикатор OFF: Зеленый (спокойно)

• Логика: Сравнивает полученные данные с заданными сообщениями

Gas (Датчик газа)

• Иконка: ☁️

• Состояние: Read-only

• Сообщение ON: 'gas'

• Сообщение OFF: 'no_gas'

• Индикатор ON: Красный

• Индикатор OFF: Зеленый

Rain (Датчик дождя)

• Иконка: 🌧️

• Состояние: Read-only

• Сообщение ON: 'rain'

• Сообщение OFF: 'no_rain'

• Индикатор ON: Синий (идет дождь)

• Индикатор OFF: Серый (сухо)

Свойства сенсоров:

• Layout: Горизонтальный ряд из 3

• Размер: Маленькие карточки

• Некликабельны: Только отображают состояние

• Обновление: Автоматически при получении данных от BLE

• Настройка: Settings → Smart Home → Sensors

  • Label (название)

  • On Message (сообщение для состояния ON)

  • Off Message (сообщение для состояния OFF)

3. AC Control Panel (Панель управления кондиционером)

Открывается при клике на кнопку AC.

Кнопки управления режимом:

Mode Buttons (верхний ряд):

1. Cool (Охлаждение)

   • Иконка: ❄️

   • Команда: 'C'

   • Цвет: Синий

   • Вибрация: 30ms

2. Heat (Обогрев)

   • Иконка: 🔥

   • Команда: 'H'

   • Цвет: Красный

   • Вибрация: 30ms

3. Dry (Осушение)

   • Иконка: 💧

   • Команда: 'Y'

   • Цвет: Желтый

   • Вибрация: 30ms

4. Fan (Вентилятор)

   • Иконка: 🌀

   • Команда: 'N'

   • Цвет: Зеленый

   • Вибрация: 30ms

Temperature Control (управление температурой):

5. Кнопка - (Понизить температуру)

   • Внешний вид: Большой минус в круге

   • Команда: 'V'

   • Диапазон: 16°C - 30°C

   • Шаг: -1°C

   • Блокировка: При достижении минимума (16°C)

   • Вибрация: 30ms

6. Дисплей температуры

   • Внешний вид: Большое число с °C

   • Диапазон: 16-30

   • Цвет:

     • Синий (16-20°C)

     • Зеленый (21-24°C)

     • Оранжевый (25-27°C)

     • Красный (28-30°C)

   • Некликабелен: Только отображение

7. Кнопка + (Повысить температуру)

   • Внешний вид: Большой плюс в круге

   • Команда: 'Z'

   • Диапазон: 16°C - 30°C

   • Шаг: +1°C

   • Блокировка: При достижении максимума (30°C)

   • Вибрация: 30ms

Set Temperature Button:

8. Кнопка Set (Установить температуру)

   • Расположение: Под дисплеем температуры

   • Цвет: Синий

   • Команда: 'T' + temperature (например, 'T24' для 24°C)

   • Функция: Отправляет установленную температуру на устройство

   • Вибрация: 30ms

Power Buttons (нижний ряд):

9. Turn On (Включить AC)

   • Цвет: Зеленый

   • Команда: 'K' (совпадает с AC ON)

   • Вибрация: 30ms

10. Turn Off (Выключить AC)

    • Цвет: Красный

    • Команда: 'k' (совпадает с AC OFF)

    • Вибрация: 30ms

Кнопка Close (Закрыть панель):

• Расположение: Правый верхний угол панели

• Иконка: ✕

• Функция: Закрывает AC Control Panel

• Вибрация: 30ms

Настройка AC:

• Settings → Smart Home → AC Control

• Можно изменить все команды:

  • On/Off команды

  • Режимы (Cool, Heat, Dry, Fan)

  • Температура +/-

  • Префикс Set Temperature (по умолчанию „T“)

---

SettingsPanel (Панель настроек)

Открывается: Клик на иконку шестеренки в любой панели

Режимы (зависит от контекста):

General Settings (Общие настройки)

Language (Язык):

• Тип: Dropdown / Radio buttons

• Опции: Русский, English, Қазақша

• Сохранение: localStorage через localization service

Theme (Тема):

• Тип: Toggle

• Опции: Light / Dark

• Сохранение: appSettings service

• TODO: Пока не реализовано (только dark)

Vibration (Вибрация):

• Тип: Toggle

• Опции: Enabled / Disabled

• Сохранение: appSettings service

• Применение: Ко всем кнопкам приложения

Control Panel Settings (при открытии из ControlPanel)

Настройка 9 кнопок:

• Forward, Backward, Left, Right (D-pad)

• X, Y, A, B (Action buttons)

• Stop

Для каждой кнопки:

• Поле Command: Текстовое поле (1-20 символов)

• Автосохранение: При изменении

• Валидация: Любая строка

• Reset: Кнопка восстановления по умолчанию

Terminal Settings (при открытии из TerminalPanel)

Macro Buttons (12 макросов):

Для каждого макроса (M1-M12):

• Label: Текст на кнопке (отображаемое имя)

• Command: Команда для отправки

• Поля:

  • Input для Label (макс 20 символов)

  • Input для Command (макс 100 символов)

• Автосохранение: При изменении

• Color Preview: Показывает цвет кнопки

Smart Home Settings (при открытии из SmartHome)

Tabs:

1. Devices Tab (Устройства):

Для каждого из 6 устройств:

• Label: Название (макс 20 символов)

• On Command: 1 символ (A-Z, a-z, 0-9)

• Off Command: 1 символ

• Валидация: Только 1 символ, алфавитно-цифровой

• Автосохранение

2. Sensors Tab (Сенсоры):

Для каждого из 3 сенсоров:

• Label: Название

• On Message: Сообщение для состояния ON (макс 50 символов)

• Off Message: Сообщение для состояния OFF

• Автосохранение

3. AC Control Tab (Управление AC):

• On Command: 1 символ (по умолчанию „K“)

• Off Command: 1 символ (по умолчанию „k“)

• Cool Command: 1 символ („C“)

• Heat Command: 1 символ („H“)

• Dry Command: 1 символ („Y“)

• Fan Command: 1 символ („N“)

• Temp Up Command: 1 символ („Z“)

• Temp Down Command: 1 символ („V“)

• Temp Set Prefix: 1 символ („T“)

4. Rooms Tab (Комнаты):

Управление комнатами (макс 6):

• Add Room Button: Добавить новую комнату

  • Поля: Name, Icon (emoji picker)

• Edit Room: Изменить существующую

• Delete Room: Удалить комнату

• Reorder: Изменить порядок (drag-and-drop - TODO)

Общие элементы SettingsPanel:

• Close Button (X): Закрыть настройки

• Tabs: Переключение между разделами (если применимо)

• Scroll: Вертикальная прокрутка при необходимости

• Backdrop: Затемненный фон, клик закрывает панель

• Animation: Slide-in/out анимация

---

Состояния кнопок

Active (Активная):

• Яркий цвет

• Тень

• Анимация при клике (scale down)

Inactive (Неактивная):

• Серый цвет

• Нет тени

• Полупрозрачность

Disabled (Отключенная):

• Серый цвет

• Курсор: not-allowed

• Не реагирует на клики

Pressed (Нажатая):

• Scale: 0.95 (уменьшение)

• Более темный цвет

• Внутренняя тень

Hover (Наведение):

• Легкий scale up (1.05)

• Увеличенная тень

• Transition: smooth

---

Визуальная обратная связь

Все кнопки имеют:

1. Haptic Feedback: Вибрация 30ms (или указанная)

2. Visual Animation: Scale transform при клике

3. Color Change: Изменение цвета при активации

4. Shadow: Динамическая тень

5. Sound: Нет (только вибрация)

Дополнительно:

• Loading State: Spinner при подключении

• Success State: Зеленая галочка (кратковременно)

• Error State: Красная обводка + вибрация [50,50,50]

---

Протокол коммуникации

UART over BLE

• Формат данных: UTF-8 строки

• Длина команды: 1 символ до 20 байт на пакет

• Baud Rate: 9600 (Arduino default)

Примеры команд

Terminal Mode:

Любая текстовая строка + Enter

RC Car Mode:

'F' - Вперед
'B' - Назад
'L' - Влево
'R' - Вправо
'S' - Стоп

Smart Home Mode:

'L' - LED Вкл
'l' - LED Выкл
'K' - AC Вкл
'k' - AC Выкл
'T24' - Установить температуру 24°C
[Настраиваются в Settings]

Важно: Все команды умного дома - одиночные символы (A-Z, a-z, 0-9), case-sensitive.

Мультиязычность

Поддерживаемые языки:

• 🇷🇺 Русский (ru)

• 🇬🇧 Английский (en)

• 🇰🇿 Казахский (kk)

Переключение: Кнопка с названием языка в правом верхнем углу

Файл: src/services/localization.ts

Settings Services

Все настройки сохраняются в localStorage:

• controlPanelSettings - настройки кнопок геймпада

• buttonSettings - legacy настройки (совместимость)

• macroSettings - макросы терминала (12 кнопок)

• smartHomeSettings - команды устройств/сенсоров/AC

• roomSettings - конфигурация комнат (макс 6)

• appSettings - вибрация, тема, язык

Особенности UI/UX

Responsive Design

Tailwind breakpoints:

• Base: mobile portrait

• landscape: - mobile landscape

• sm: - desktop (≥640px)

• sm:landscape: - desktop landscape

Vibration Feedback

Вызывается на всех кликах кнопок:

appSettings.vibrate(30); // Обычный клик
appSettings.vibrate([50, 50, 50]); // Ошибка

Fullscreen API

• Автоматически запрашивается на мобильных устройствах

• Скрыт на iOS (не поддерживается)

• Доступен через кнопку на Android/Desktop

• iOS альтернатива: «Add to Home Screen»

Orientation Lock

Использует JavaScript (CSS media queries ненадежны):

const width = window.innerWidth;
const height = window.innerHeight;
const isLandscape = width > height && width < 1024;

Обработка ошибок

ErrorBoundary

Файл: src/components/ErrorBoundary.tsx

Отлавливает все React ошибки и показывает:

• Иконка предупреждения

• Сообщение об ошибке

• Кнопка «Reload Page»

• Ссылка на GitHub Issues

UnsupportedBrowser

Файл: src/components/UnsupportedBrowser.tsx

Показывается на iOS/Safari/Firefox:

• Объяснение проблемы

• Список поддерживаемых браузеров

• Рекомендации для iOS пользователей

• Ссылка на GitHub

Deployment на GitHub Pages

URL: https://alash-electronics.github.io/bluetoothWebApp/

Конфигурация:

// vite.config.ts
export default defineConfig({
  plugins: [react(), basicSsl()],
  base: '/bluetoothWebApp/',
})

Команда деплоя:

npm run deploy

Процесс:

1. Запускает npm run build (predeploy script)

2. Компилирует TypeScript + собирает bundle

3. Деплоит папку dist/ в ветку gh-pages

4. GitHub Pages автоматически обновляется (1-2 минуты)

Branch: gh-pages (создается автоматически пакетом gh-pages)

Arduino примеры

Директория: ble-controller/arduino-examples/

terminal_basic

Простой эхо-сервер для тестирования терминала

rc_car_control

Управление моторами для RC машины (L298N driver)

smart_home_basic

Управление реле и LED для умного дома

Общие детали:

• SoftwareSerial на пинах 10/11 (по умолчанию)

• Baud rate: 9600

• HM-10 RX требует 3.3V (делитель напряжения на 5V Arduino)

• Команды - одиночные символы

Известные проблемы и решения

1. Белый экран на iOS

Проблема: iOS не поддерживает Web Bluetooth API Решение: Показывается UnsupportedBrowser компонент с объяснением

2. Fullscreen не работает на iOS

Проблема: Fullscreen API не поддерживается на iOS Решение: Кнопка автоматически скрывается. Альтернатива: «Add to Home Screen»

3. Логотип не отображается

Проблема: Неправильные пути с base path Решение: Используется ${import.meta.env.BASE_URL}logo.png

4. Ошибки после splash screen

Проблема: Ошибки fullscreen API крашат приложение Решение: Добавлены try-catch блоки и ErrorBoundary

Коммиты и история изменений

Последние важные коммиты:

1. 5bb5bd9 - fix: Hide fullscreen button on iOS devices

2. ce5cd28 - fix: Add comprehensive error handling for mobile browsers

3. db1c565 - fix: Add iOS/Safari browser detection and unsupported browser screen

4. 727e538 - Предыдущие изменения

Полезные ссылки

• Репозиторий: https://github.com/Alash-electronics/bluetoothWebApp

• Живая демо: https://alash-electronics.github.io/bluetoothWebApp/

• Issues: https://github.com/Alash-electronics/bluetoothWebApp/issues

• Arduino примеры: https://github.com/Alash-electronics/bluetoothWebApp/tree/main/ble-controller/arduino-examples

Web Bluetooth API документация

• MDN: https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API

• Chrome Platform Status: https://www.chromestatus.com/feature/5264933985976320

• Can I Use: https://caniuse.com/web-bluetooth

Контакты и поддержка

• GitHub Issues: https://github.com/Alash-electronics/bluetoothWebApp/issues

• Discussions: https://github.com/Alash-electronics/bluetoothWebApp/discussions

• Email: через GitHub профиль

Contributing

Читайте CONTRIBUTING.md для:

• Руководство по code style

• Процесс pull requests

• Тестирование перед коммитом

• Commit message conventions

Лицензия

MIT License - можно свободно использовать, изменять и распространять.

---

Последнее обновление: 27 октября 2025 Версия документа: 2.0 Автор: Alash Electronics с помощью Claude Code

Changelog v2.0:

• Добавлен подробный раздел «Кнопки и элементы управления»

• Документированы все системные кнопки

• Описаны кнопки каждого режима (ControlPanel, JoystickPanel, Terminal, SmartHome)

• Добавлена информация о состояниях кнопок и визуальной обратной связи

• Детальное описание панели настроек (SettingsPanel)

• Информация о команд по умолчанию и настройке всех элементов