================================================================================
WEATHER CONTROL SYSTEM v2.5
Технічна документація та інструкція
================================================================================
1. ПРИЗНАЧЕННЯ СИСТЕМИ
--------------------------------------------------------------------------------
Weather Control System — це серверний застосунок для автоматизованого
керування кондиціонерами на основі погодних умов. Система аналізує
температуру та хмарність, отримані з API погодних сервісів, і приймає
рішення про ввімкнення або вимкнення кондиціонерів. Безпосереднє керування
здійснюється через ESP32 з реле, яке імітує натискання кнопки на дротовому
пульті кондиціонера.
Основні можливості:
- Автоматичне керування кондиціонерами за погодними умовами
- Підтримка трьох джерел погодних даних (WeatherAPI, OpenWeatherMap, VisualCrossing)
- Веб-інтерфейс для моніторингу та налаштування
- Оновлення програмного забезпечення через веб-інтерфейс (OTA)
- Захист від повторних натискань кнопок
- Логування подій у CSV-файл
- Модульна архітектура коду
2. АРХІТЕКТУРА ПРОЕКТУ
--------------------------------------------------------------------------------
Проект складається з двох основних частин:
A. Серверна частина (Python/Flask)
Розгортається на Windows-машині. Виконує функції:
- Отримання погодних даних
- Аналіз умов та прийняття рішень
- Відправка команд на пристрої ESP32
- Веб-інтерфейс для користувача
- Логування подій
B. Виконавчі пристрої (ESP32 + реле)
Підключаються до дротових пультів кондиціонерів. Виконують функції:
- Отримання HTTP-команд від сервера
- Керування реле для імітації натискань кнопок
- Захист від повторних натискань
- Надання статусу серверу (зворотний зв'язок)
Файлова структура серверної частини:
weather_control/
├── app.py # Головний файл (Flask-маршрути)
├── config.py # Налаштування та конфігурація
├── weather.py # Отримання погоди (3 API)
├── devices.py # Робота з пристроями ESP32
├── logger.py # Логування (CSV, консоль)
├── storage.py # Збереження/завантаження даних
├── scheduler.py # Планувальник перевірок
├── ota.py # Механізм OTA-оновлень
├── .env # API-ключі (не зберігаються в репозиторії)
├── requirements.txt # Залежності Python
├── templates/
│ ├── index.html # Головна сторінка веб-інтерфейсу
│ └── admin.html # Адміністративна панель
3. ВСТАНОВЛЕННЯ ТА ЗАПУСК
--------------------------------------------------------------------------------
3.1. Вимоги до системи
- Windows 7/10/11 або Windows Server
- Python 3.9 або новіше
- Встановлені залежності з requirements.txt
3.2. Встановлення залежностей
Відкрийте командний рядок у папці проекту та виконайте:
pip install -r requirements.txt
Склад requirements.txt:
flask==2.3.3
flask-cors==4.0.0
requests==2.31.0
python-dotenv==1.0.0
schedule==1.2.0
3.3. Налаштування API-ключів
Відредагуйте файл .env у кореневій папці проекту:
WEATHER_API_KEY=ваш_ключ_openweathermap
WEATHERAPI_KEY=ваш_ключ_weatherapi
VISUALCROSSING_KEY=ваш_ключ_visualcrossing
Для роботи системи достатньо хоча б одного ключа. Джерело даних
обирається у веб-інтерфейсі.
3.4. Налаштування пристроїв
У файлі config.py відредагуйте словник devices, вказавши IP-адреси
ваших ESP32:
'devices': {
'Офіс 2 пов.': {'ip': '192.168.1.131', ...},
'Офіс 1 пов.': {'ip': '192.168.1.132', ...},
}
3.5. Запуск сервера
python app.py
Після запуску сервер доступний за адресою:
http://localhost:5500
4. ЛОГІКА РОБОТИ СИСТЕМИ
--------------------------------------------------------------------------------
Система перевіряє погодні умови через заданий інтервал (за замовчуванням
кожні 10 хвилин). Для кожної перевірки виконується така послідовність:
4.1. Перевірка робочого часу
Якщо поточний час поза межами робочого діапазону (за замовчуванням
08:00-19:00), система примусово вимикає всі кондиціонери.
Причина: "Поза робочим часом".
4.2. Перевірка температури
Якщо температура нижче заданого мінімуму (за замовчуванням 18°C),
система вимикає кондиціонери.
Причина: "Температура X°C нижче мінімальної Y°C".
4.3. Перевірка хмарності
Якщо хмарність поза заданим діапазоном (за замовчуванням 0-50%),
система вимикає кондиціонери.
Причина: "Хмарність X% поза діапазоном Y%-Z%".
4.4. Успішне виконання умов
Якщо всі умови виконані, система вмикає кондиціонери.
Причина: "Умови виконано: t=X°C, хмарність=Y%".
4.5. Захист від повторних команд
Перед відправкою команди на ESP32 сервер перевіряє поточний стан
пристрою. Якщо пристрій вже в потрібному стані, команда не
відправляється. Додатково сам ESP32 блокує повторне виконання
тієї самої команди (ON після ON або OFF після OFF).
5. ВЕБ-ІНТЕРФЕЙС
--------------------------------------------------------------------------------
5.1. Головна сторінка (http://localhost:5500)
Статус системи:
- Відображає поточний стан (АКТИВНО/НЕАКТИВНО)
- Причину останньої зміни стану
- Час останньої зміни
Погодні дані:
- Поточна температура
- Хмарність у відсотках
- Текстовий опис погоди
- Час останнього оновлення даних
- Назва активного джерела API
Службова інформація:
- Робочий час
- Інтервал перевірок
- Кількість запитів за місяць
- Кількість увімкнень та вимкнень за сьогодні
Налаштування:
- Початок та кінець робочого часу
- Мінімальна температура для запуску
- Діапазон хмарності (від/до)
- Інтервал перевірок
- Джерело погодних даних
Пристрої:
- Назва пристрою
- IP-адреса
- Остання виконана команда
- Реальний стан (отриманий від ESP32)
- Кнопки ручного керування ON/OFF
Лог подій:
- Останні 30 подій системи з часовими мітками
5.2. Адміністративна панель (http://localhost:5500/admin)
Оновлення ПЗ (OTA):
- Завантаження .py файлу для оновлення серверної частини
- Завантаження .zip архіву для оновлення всього проекту
- Автоматичне створення резервної копії перед оновленням
- Кнопка відновлення з резервної копії
Скидання налаштувань:
- Повернення до заводських значень (08:00-19:00, 18°C, 0-50%, 10хв)
6. ESP32 ТА РЕЛЕ
--------------------------------------------------------------------------------
6.1. Принцип роботи
ESP32 отримує HTTP-команди від сервера та керує реле, яке імітує
натискання кнопки на дротовому пульті кондиціонера. Реле підключається
до сенсорної кнопки через резистор 470 кОм (або методом "сендвіча" з
металевою пластиною).
6.2. Команди
/on — одне натискання реле (тривалість налаштовується, за замовч. 500 мс)
/off — два натискання з паузою (за замовчуванням 5000 мс)
6.3. Захист від повторних натискань
Після виконання команди ON пристрій блокує повторний ON доти, доки
не буде виконана команда OFF. Аналогічно після OFF блокується повторний
OFF. Це запобігає розсинхронізації стану кондиціонера.
6.4. Додаткове блокування (cooldown)
Після будь-якої операції встановлюється блокування на 40 секунд
(налаштовується), протягом якого будь-які команди відхиляються.
6.5. Зворотний зв'язок
Сервер періодично (кожні 15 секунд) опитує ESP32 через /status
для отримання реального стану пристрою (on/off/locked).
6.6. Коди відповідей ESP32
200 — команда виконана успішно
423 — команду відхилено (заблоковано або повтор)
7. ЛОГУВАННЯ
--------------------------------------------------------------------------------
7.1. Консольний лог
У реальному часі виводиться у вікно командного рядка. Містить
інформацію про запуск, перевірки, відправлені команди, помилки.
7.2. CSV-лог (system_log.csv)
Кожна значуща подія записується у файл. Доступний для завантаження
через веб-інтерфейс: http://localhost:5500/api/csv-log
Або через кнопку в адмін-панелі.
Формат CSV:
Дата, Час, Тип події, Деталі, Температура, Хмарність, Джерело
Типи подій:
- SERVER_START — запуск сервера
- CONFIG_UPDATE — зміна налаштувань
- SYSTEM_ON / SYSTEM_OFF — зміна стану системи
- DEVICE_ON / DEVICE_OFF — команда на пристрій
- OTA_UPDATE — оновлення ПЗ
- RESTORE — відновлення з бекапу
- RESET — скидання налаштувань
7.3. Системний лог (в пам'яті)
Зберігається 100 останніх записів. Відображається у веб-інтерфейсі
в розділі "Останні події".
8. OTA-ОНОВЛЕННЯ
--------------------------------------------------------------------------------
8.1. Підтримувані формати
.py — оновлення тільки головного файлу сервера
.zip — оновлення всього проекту (app.py, модулі, шаблони, статика)
8.2. Структура ZIP-архіву для оновлення
У корені архіву повинні знаходитися файли без додаткової батьківської
папки:
update_v2.6.zip
├── app.py
├── config.py
├── weather.py
├── devices.py
├── logger.py
├── storage.py
├── scheduler.py
├── ota.py
└── templates/
├── index.html
└── admin.html
└── guide.html
Увага: неправильна структура ZIP (з додатковою папкою всередині)
призведе до того, що файли не заміняться.
8.3. Резервне копіювання
Перед кожним оновленням створюється повна копія папки проекту в
директорію backup/. Файли .json, .env та backup/ виключаються з копії.
8.4. Відновлення
Кнопка "Відновити з бекапу" в адмін-панелі повертає всі файли
до попередньої версії та перезавантажує сервер.
8.5. Перезапуск після оновлення
Після встановлення оновлення створюється тимчасовий _restart.bat,
який перезапускає сервер з новими файлами, після чого самовидаляється.
9. ТИПОВІ СЦЕНАРІЇ
--------------------------------------------------------------------------------
9.1. Звичайний робочий день
08:00 — система виходить з нічного режиму
08:00-19:00 — перевірки погоди кожні 10 хв
Якщо тепло і ясно — кондиціонери вмикаються
Якщо холодно або хмарно — кондиціонери вимикаються
19:00 — система примусово вимикає кондиціонери
9.2. Ручне керування
Користувач може вручну ввімкнути або вимкнути конкретний пристрій
через веб-інтерфейс. Система врахує цей стан і не буде відправляти
повторну команду.
9.3. Збій мережі
Якщо ESP32 недоступний, сервер позначає його статус як "offline"
і пропускає при наступних перевірках.
9.4. Зміна джерела погоди
Користувач може змінити джерело API у веб-інтерфейсі. Система
миттєво переключається на нове джерело без перезавантаження.
10. НАЛАШТУВАННЯ ЗА ЗАМОВЧУВАННЯМ
--------------------------------------------------------------------------------
work_start: 08:00
work_end: 19:00
temp_min: 18°C
cloud_min: 0%
cloud_max: 50%
check_interval: 10 хвилин
api_source: weatherapi
port: 5500
11. ВИЯВЛЕННЯ ТА УСУНЕННЯ НЕСПРАВНОСТЕЙ
--------------------------------------------------------------------------------
11.1. Сервер не запускається
- Перевірте, чи встановлені всі залежності (pip list)
- Перевірте, чи порт 5500 не зайнятий іншим процесом
- Перевірте наявність файлу .env з API-ключами
11.2. Погода не оновлюється
- Перевірте підключення до Інтернету
- Перевірте валідність API-ключів у файлі .env
- Спробуйте змінити джерело API у веб-інтерфейсі
11.3. Кондиціонери не реагують
- Перевірте, чи доступний ESP32 за вказаною IP-адресою
- Перевірте статус пристрою у веб-інтерфейсі (online/offline)
- Перевірте підключення реле до пульта кондиціонера
11.4. Система не вмикається при хорошій погоді
- Перевірте, чи знаходитесь ви в робочому часі
- Перевірте налаштування температури та хмарності
- Перевірте, чи пристрої не в стані "offline" або "locked"
12. КОНТАКТИ ТА ПІДТРИМКА
--------------------------------------------------------------------------------
Проект розроблено як індивідуальне рішення для автоматизації
керування кондиціонерами на основі погодних умов.
Розробник: sicboy000@gmail.com
Дата: 2026-05-25
Версія системи: 2.5 (Dark Edition)