JAAM Fusion 5.x

Репозиторій містить файли прошивки JAAM Fusion (кодова назва нової версії) - прошивки для ESP32, що дозволяє за допомогою розміщених на мапі України адресних світлодіодів відображати такі типи інформації:

• 🚨 Повітряні тривоги в реальному часі
• 🌡️ Погода в регіонах України
• ☢️ Радіаційне забруднення
• ⚡ Стан електромережі
• 🇺🇦 Візуальні зображення (прапор України та інші)
• 💡 Режим настільної лампи

Крім цього, підтримується окремий OLED-дисплей, який відображає поточний час, погоду, радіацію, стан електромережі, глобальні сповіщення та сервісні повідомлення.

КУПИТИ ГОТОВУ МАПУ МОЖНА ТУТ

• WIKI по прошивці
• FLASHER - тут можна залити свіжу прошивку прямо з браузера!
• ТЕЛЕГРАМ КАНАЛ ПРОЕКТУ
• ЧАТ ПРОЕКТУ
• ПОРТАЛ ДАНИХ

• CONTROLS_GUIDE.md - Детальний довідник з додавання нових UI контролів
• WEB_ASSETS_README.md - Система компресії веб-ресурсів та кешування

Революційна можливість налаштування будь-якої апаратної конфігурації світлодіодів!

• Повна свобода конфігурації: Підтримка будь-якої кількості та розташування LED
• Редактор карти LED: Зручний web-інтерфейс для прив'язки LED до регіонів
• Гнучкість: Від простої стрічки до складних матричних конфігурацій
• Збереження конфігурації: Маппінг зберігається в пам'яті та відновлюється після перезавантаження
• Підтримка різних форматів: Можливість використання різних типів LED (WS2812B тощо) в одному проєкті

Тепер ви не обмежені стандартними конфігураціями - створюйте власні унікальні карти!

• Модульна структура коду: Кожен компонент системи винесено в окремий клас
• Асинхронна обробка: Використання ArduinoAsync та FreeRTOS для ефективної багатозадачності
• Оптимізація пам'яті: Покращене управління heap memory та дефрагментація
• WebSocket протокол: Real-time оновлення через власний сервер jaam.net.ua

• ESP32-S3 - повна підтримка з оптимізацією під 4MB Flash
• ESP32-C3 - підтримка компактних плат
• Матричні LED конфігурації - підтримка до 400 LED для великих карт
• DFPlayer PRO - відтворення високоякісних аудіофайлів (замість buzzer мелодій)

• GZIP компресія assets - зменшення розміру веб-файлів на 73.7%
• Real-time API через WebSocket - швидкий обмін даними з клієнтами
• Динамічне стиснення JSON/HTML - економія трафіку та RAM
• ETag кешування - мінімізація повторних завантажень статичних ресурсів
• Редактор карти та кольорів - зручне налаштування LED

• Нові типи анімацій:

  • Fade (згасання)
  • Blink (блимання)
  • Blend Fade (плавний перехід)
  • Pulse (пульсація)
  • One Way Blend Fade (плавний перехід в одному напрямку)

• Покращена підтримка сенсорів:

  • BME280 (температура, вологість, тиск)
  • BMP280 (температура, тиск)
  • SHT2x, SHT3x, AHT30 (температура та вологість)
  • BH1750 (цифровий сенсор освітлення)

• Flexible Display Support:

  • SSD1306 (128x32, 128x64)
  • SH1106G (128x64)
  • SH1107 (128x64)
  • Підтримка обертання дисплею (0°, 90°, 180°, 270°)

• OTA Updates - оновлення "по повітрю" через веб-інтерфейс
• Канали розповсюдження: Production (стабільні) та Beta (експериментальні)
• Firmware validation - перевірка цілісності прошивки перед встановленням

Фронтальна частина:

• 124 LED WS2812B-2020: Підсвічування областей України (м. Київ - окремий LED)
• OLED дисплей (SH1106G, 1.3"): Час, температура, інформація
• 5 сервісних LED: Індикація стану системи (живлення, WiFi, дані, API, оновлення)
• Сенсор освітлення (BH1750): Автоматичне регулювання яскравості
• Динамік (buzzer): Звукові сповіщення з апаратним вимикачем

Задня частина:

• 44 LED ambient light: Ефектна підсвітка
• Сенсор клімату (BME280): Температура, вологість, тиск
• ESP32: Центр керування
• Мікрофон (ICS-43432): Резерв на майбутнє, з апаратним вимикачем
• Дві кнопки: Управління режимами, перезавантаження, перепрошивка
• Виводи ESP32: Для розширення функціоналу

Живлення:

• USB-C (живлення та прошивка)
• DC (5.5×2.1mm, 5–24В)

Найсучасніша конфігурація з розширеними можливостями:

• 405 LED WS2812B (найбільша конфігурація)
• Матрична розкладка для максимальної детальної візуалізації
• 39 LED для фонової підсвітки
• Підтримка складних анімацій
• 🎯 Підтримка тривог за районами та містами (де це підтримує офіційне API)
  • Детальне відображення тривог на рівні районів
  • Інші міста: підтримка додається в міру розширення офіційного API
  • Автоматичне оновлення підтримки нових міст з новими версіями прошивки

• Platform: ESP32 (Espressif32 @ 6.12.0)
• Framework: Arduino
• Async Processing: ArduinoAsync для non-blocking операцій
• WebSocket: Real-time комунікація з сервером
• LED Control: Adafruit NeoPixel
• NTP: Синхронізація часу
• Display: U8g2 для OLED дисплеїв

Відображення повітряних тривог на базі офіційного API ukrainealarm.com та сторонніх інтеграцій

Офіційне API:

• Стандартна тривога (червоний)
• Загроза крилатих та авіаційних ракет (фіолетовий)
• Загроза ударних БПЛА (помаранчевий)

e-Tryvoga:

• Загроза крилатих та авіаційних ракет (фіолетовий)
• Загроза ударних БПЛА (помаранчевий)
• Загроза КАБ (жовтий)
• Загроза балістичних ракет (блакитний)
• Вибухи в регіонах (білий спалах)
• Розвідувальні БПЛА (синій спалах)

Спеціальні функції:

• Виділення домашнього регіону
• Підсвічування нових тривог (інший колір перші N секунд)
• Підсвічування відбою тривоги (інший колір перші N секунд)

Відображення температури за даними OpenWeatherMap

• Кольорова індикація температури
• Підтримка різних температурних шкал

Відображення синьо-жовтого прапора України

• Довільні кольори для всіх регіонів
• Підтримка кастомних палітр
• Color picker в web-інтерфейсі

Мапа не відображає нічого (LED вимкнені)

• Великий чіткий час
• Дата
• Синхронізація через NTP
• Підтримка різних часових поясів

• Температура у домашньому регіоні
• Дані з OpenWeatherMap
• Автоматичне оновлення

• Uptime пристрою
• Використання пам'яті
• Сила WiFi сигналу
• Статус WebSocket з'єднання
• Температура CPU

• Температура в кімнаті
• Вологість
• Атмосферний тиск (для BME280)

Доступ до пристрою:

• За IP адресою: http://<IP_ADDRESS>
• За mDNS: Кожен пристрій має індивідуальне mDNS ім'я для автоматичного виявлення в локальній мережі

Налаштування мапи:

• Режим роботи (тривоги, погода, прапор, лампа)
• Яскравість (загальна, денна, нічна, автоматична)
• Кольори для різних типів тривог
• Яскравість для кожного типу тривоги окремо
• Домашній регіон
• Налаштування анімацій

Налаштування дисплею:

• Режим відображення
• Тип дисплею (SSD1306, SH1106G, SH1107)
• Роздільність (128x32 або 128x64)
• Обертання екрану

Налаштування LED:

• Піни підключення (main, background, service)
• Кількість LED в кожній стрічці
• Формат кольорів (RGB, GRB, RGBW тощо)
• 🌟 Візуальний редактор карти - революційний функціонал кастомного маппінгу:
  • Інтерактивне призначення кожного LED до регіону
  • Підтримка множинного вибору LED для одного регіону
  • Візуальний попередній перегляд конфігурації
  • Збереження та відновлення налаштувань
  • Підходить для будь-якої апаратної конфігурації (від 1 до 400 LED)
• Редактор фонових кольорів з попереднім переглядом

Налаштування сенсорів:

• Тип кліматичного сенсора (BME280, SHT2x, SHT3x, AHTxx)
• Тип сенсора освітлення (BH1750)
• Калібрування

Налаштування звуку:

• Buzzer або DFPlayer PRO
• Мелодії для подій (тривога, відбій, хвилина мовчання)
• Гучність
• Годинні сповіщення

Налаштування кнопок:

• Призначення дій на кожну кнопку
• Коротке/довге натискання
• Доступні дії:
  • Перемикання режиму мапи
  • Перемикання режиму дисплею
  • Увімкнення/вимкнення мапи
  • Увімкнення/вимкнення дисплею
  • Нічний режим
  • Перезавантаження (лише довге натискання)

Інтеграція Home Assistant:

• Доступна HACS інтеграція (див. розділ "Інтеграція з Home Assistant")
• Керування всіма функціями через HA
• Сенсори, перемикачі, кнопки та інше

Налаштування оновлень:

• Канал оновлень (Production/Beta)
• Перевірка наявності оновлень
• Оновлення одним кліком
• Відображення версії прошивки

Системна інформація:

• Serial консоль в браузері
• Діагностична інформація
• Статистика пам'яті
• Логи роботи

Підтримка мелодій:

• Гімн України
• Ой у лузі червона калина
• Козацький марш
• Harry Potter Theme
• Сирена
• Star Trek Communicator
• Star Wars Theme
• Imperial March
• Star Trek Intro
• Indiana Jones Theme
• Back to the Future
• Kiss - I Was Made For Lovin' You
• The Little Mermaid
• Nokia Tune
• Pac-Man
• Щедрик
• X-Men Theme
• The Avengers

• Відтворення MP3 файлів
• Регулювання гучності (0-30)
• Підтримка SD карток
• Висока якість звуку
• Можливість завантаження власних треків

Події зі звуковим супроводом:

• Початок тривоги
• Відбій тривоги
• Натискання кнопок
• Годинні сповіщення
• Хвилина мовчання
• Стартове привітання

• Фіксована: Одне значення для всієї доби
• За часом: Автоматичне перемикання день/ніч за розкладом
• За сенсором: Автоматичне перемикання за освітленням в кімнаті
• Ручна: Натисканням на кнопку

Окреме налаштування для кожного типу:

• Стандартна тривога
• Нова тривога (перші N секунд)
• Відбій тривоги (перші N секунд)
• Загроза крилатих та авіаційних ракет
• Загроза ударних БПЛА
• Розвідувальні БПЛА
• Загроза КАБ
• Загроза балістичних ракет
• Вибухи
• Домашній регіон

🌟 Революційна можливість: Тепер ви можете створити мапу з будь-якою конфігурацією LED!

Приклади стандартних конфігурацій:

• JAAM 1.3: 26 LED (Київ окремо)
• JAAM 2.1: 26 LED (класична)
• JAAM 3.2: 405 LED (матрична, з підтримкою районів та міст)
• Ваша власна: від 1 до 400 LED

Як працює кастомний маппінг:

1. Підключіть LED стрічку будь-якої довжини
2. Відкрийте візуальний редактор в web-інтерфейсі
3. Призначте кожен LED (або групу LED) до регіону України
4. Збережіть конфігурацію - вона зберігається в пам'яті
5. Насолоджуйтесь унікальною картою!

Переваги кастомного маппінгу:

• Створення мапи з нестандартною кількістю LED
• Призначення декількох LED одному регіону (для акцентування)
• Підтримка матричних конфігурацій будь-якої форми
• Можливість пропуску регіонів (якщо не потрібні)
• Адаптація під вашу фізичну конструкцію мапи

Фонова підсвітка:

• Режим "домашній регіон" - копіює колір та анімацію
• Режим "кастомний колір" - фіксований колір
• Режим "карта кольорів" - індивідуальні кольори для кожного LED

Індикація стану системи:

• 🔴 Живлення - Червоний: пристрій працює
• 🔵 WiFi - Синій: підключено до WiFi
• 🟢 Дані - Зелений: отримання даних з серверу
• 🟡 API - Жовтий: HA підключено
• ⚪ Оновлення - Білий: доступне оновлення прошивки

JAAM Fusion повністю інтегрується в Home Assistant через спеціальну HACS інтеграцію.

1. Установіть HACS (якщо ще не встановлено) - hacs.xyz
2. Додати репозиторій інтеграції:
   • Відкрийте HACS в Home Assistant
   • Перейдіть до "Інтеграції" (Integrations)
   • Натисніть на "🔵 Custom repositories"
   • Додайте: https://github.com/J-A-A-M/jaam_ha
   • Категорія: "Integration"
3. Завантажте інтеграцію:
   • Знайдіть "JAAM" в HACS
   • Натисніть "Download"
4. Перезавантажте Home Assistant
5. Додайте інтеграцію:
   • Налаштування → Пристрої та служби → Інтеграції
   • Натисніть "+ Додати інтеграцію"
   • Знайдіть та оберіть "JAAM"
   • Вкажіть IP-адресу вашого JAAM пристрою

Посилання на інтеграцію: github.com/J-A-A-M/jaam_ha

Select (Вибір):

• Режим мапи (тривоги, погода, прапор, лампа, offline)
• Домашній регіон (вибір з усіх областей та районів України через сервіс HA)

Light (Освітлення - для режиму лампи):

• Колір лампи (RGB picker)
• Яскравість лампи (0-100%)

Sensor (Сенсори):

• Системна інформація:

  • Температура CPU (°C)
  • Uptime пристрою
  • WiFi uptime
  • Сила WiFi сигналу (dBm)
  • Використання пам'яті (bytes)
  • Статус WebSocket підключення
  • WebSocket uptime

• Інформація про тривоги:

  • Прапорці тривоги в домашньому регіоні
  • Температура в домашньому регіоні (з OpenWeatherMap)

• Сенсори (якщо підключені):

  • Кліматичні дані (температура, вологість, тиск з BME280/SHT3x/інших)
  • Рівень освітлення (з BH1750 або фоторезистора)

Update (Оновлення):

• Версія прошивки (поточна та доступна)
• Можливість оновлення через HA одним кліком

Примітка: Інтеграція підключається через WebSocket API на порту 81. Всі налаштування яскравості, дисплею, кнопок та інші параметри доступні через веб-інтерфейс пристрою (за IP адресою або mDNS ім'ям).

• PlatformIO (CLI або VS Code extension)
• Python 3.x (для скриптів компресії)

# Клонування репозиторію
git clone https://github.com/J-A-A-M/jaam_fusion.git
cd jaam_fusion

# Збірка для стандартної плати
platformio run -e firmware

# Збірка для ESP32-S3
platformio run -e firmware_esp32s3

# Збірка для ESP32-C3
platformio run -e firmware_esp32c3

# Збірка та завантаження
platformio run -e firmware --target upload

# Моніторинг Serial
platformio device monitor

firmware - Стандартна ESP32 firmware_esp32s3 - ESP32-S3 firmware_esp32c3 - ESP32-C3

Веб-ресурси автоматично стискаються перед збіркою завдяки tools/compress_assets.py:

• Скрипт запускається автоматично при збірці
• Генерує src/web_assets.h з стиснутими даними
• Зменшення розміру на 73.7%

Детальніше: WEB_ASSETS_README.md

// LED стрічки
#define MAIN_LED_PIN      13    // Основна стрічка (мапа)
#define BG_LED_PIN        12    // Фонова підсвітка
#define SERVICE_LED_PIN   25    // Сервісні LED

// Кнопки
#define BUTTON_1_PIN      5     // Кнопка 1 (JAAM 3)
#define BUTTON_2_PIN      0     // Кнопка 2
#define BUTTON_3_PIN      2     // Кнопка 3

// Звук
#define BUZZER_PIN        33    // Buzzer
#define DF_RX_PIN         17    // DFPlayer RX
#define DF_TX_PIN         16    // DFPlayer TX

• VCC → 3.3V
• GND → GND
• SDA → GPIO 21
• SCL → GPIO 22

BME280/BMP280 (I2C):

• VCC → 3.3V
• GND → GND
• SDA → GPIO 21
• SCL → GPIO 22

BH1750 (I2C):

• VCC → 3.3V
• GND → GND
• SDA → GPIO 21
• SCL → GPIO 22

platformio device monitor -b 115200

telnet <MDNS_NAME>
# або
telnet <IP_ADDRESS>

Всі налаштування зберігаються у внутрішній флеш-пам'яті ESP32 (Preferences/NVS):

• Відновлюються після перезавантаження
• Зберігаються після перепрошивки

1. Відкрийте веб-інтерфейс
2. Перейдіть в розділ "Оновлення прошивки"
3. Оберіть канал (Production/Beta)
4. Оберіть версію зі списку
5. Натисніть "Підтвердити" для початку оновлення

platformio run -e firmware --target upload

1. Відкрийте браузер Chrome/Edge
2. Перейдіть на https://flasher.jaam.net.ua/
3. Підключіть ESP32 через USB
4. Оберіть версію та встановіть

• MCU: ESP32 (240MHz dual-core)
• Flash: 4MB мінімум
• RAM: 520KB (heap 200KB+)
• WiFi: 2.4GHz 802.11 b/g/n

• JAAM 1.3/2.1: ~2-5W (залежно від яскравості)
• JAAM 3.2: ~3-10W (залежно від яскравості)

• WS2812B
• WS2812B-2020 (компактна версія)
• Інші сумісні з протоколом NeoPixel

jaam_fusion/
├── platformio.ini           # Конфігурація PlatformIO
├── custom_4MB.csv          # Partition table для ESP32-S3
├── README.md               # Цей файл
├── WEB_ASSETS_README.md    # Документація компресії веб-ресурсів
├── CONTROLS_GUIDE.md       # Довідник з додавання UI контролів
├── data/                   # Дані для генерації карт
│   ├── gen_data.py
│   ├── gen_data.json
│   └── ...
├── src/                    # Вихідний код прошивки
│   ├── JaamFusion.cpp      # Головний файл
│   ├── JaamConfig.h        # Конфігурація
│   ├── JaamAnimation.*     # Система анімацій
│   ├── JaamApi.*           # WebSocket API
│   ├── JaamBattery.*       # Моніторинг батареї
│   ├── JaamButton.*        # Обробка кнопок
│   ├── JaamClimateSensor.* # Кліматичні сенсори
│   ├── JaamDisplay.*       # Керування дисплеєм
│   ├── JaamFirmwareUpdate.*# OTA оновлення
│   ├── JaamHardware.*      # Апаратні конфігурації
│   ├── JaamLed.*           # Керування LED
│   ├── JaamLightSensor.*   # Сенсор освітлення
│   ├── JaamLogs.*          # Система логування
│   ├── JaamMDNS.*          # mDNS сервіс
│   ├── JaamSettings.*      # Налаштування
│   ├── JaamSiren.*         # Сирена
│   ├── JaamSound.*         # Звукова система
│   ├── JaamStorage.*       # Збереження даних
│   ├── JaamUtils.h         # Утиліти
│   ├── JaamWeb.*           # Web-сервер
│   └── web_assets.h        # Згенеровані веб-ресурси
├── tools/
│   └── compress_assets.py  # Скрипт компресії
└── web/                    # Вихідні веб-ресурси
    ├── styles.css
    ├── scripts.js
    ├── map_editor.*
    ├── bg_color_editor.*
    └── ui_schema_*.json

Ми вітаємо вклад від спільноти!

1. 🐛 Повідомляйте про баги через Issues
2. 🔧 Створюйте Pull Request з виправленнями
3. 📖 Покращуйте документацію
4. 🎨 Створюйте нові анімації та режими

Цей проєкт ліцензовано під CC BY-NC-SA 4.0 (Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International).

✅ Дозволено:

• Вільно використовувати, модифікувати та розповсюджувати код
• Для особистого, навчального та некомерційного використання
• Створювати власні версії та покращення
• Ділитися з іншими

❌ Заборонено:

• Комерційне використання без письмового дозволу
• Продаж пристроїв з цією прошивкою
• Надання платних послуг на основі прошивки
• Використання в комерційних продуктах

📋 Вимоги:

• При використанні необхідно зазначити авторство
• Модифікації мають бути під тією ж ліцензією (CC BY-NC-SA 4.0)
• Зберігати посилання на оригінальний проєкт

Якщо ви хочете використовувати JAAM Fusion в комерційних цілях (виробництво та продаж пристроїв, надання платних послуг тощо), будь ласка, зв'яжіться з нами:

• 📧 Телеграм: @jaam_project
• 💬 Чат проєкту: JAAM Discussions

Повний текст ліцензії: https://creativecommons.org/licenses/by-nc-sa/4.0/

Див. також файл LICENSE в кореневій директорії проєкту.

Цей проєкт створено в підтримку України. Якщо ви хочете допомогти:

• Stand With Ukraine
• Come Back Alive Foundation
• United24

Дякуємо всім контриб'юторам, тестувальникам та користувачам проєкту JAAM за підтримку та допомогу в розвитку!

Особлива подяка:

• Спільноті JAAM Project
• Розробникам використовуваних бібліотек
• Всім, хто підтримує проєкт

Слава Україні! 🇺🇦